homebutler

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description nonetheless adds a genuinely new trait: 'nothing is sent anywhere' — i.e. no notifications are dispatched, unlike notify_test — and that nothing is recorded. It omits where thresholds come from and what happens when a threshold is breached (warning vs. error).

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

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

The core sentence is front-loaded and efficient, but the second sentence ('which is what a running watcher does instead') is awkward and ambiguous, costing clarity rather than earning 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?

There is no output schema, so the description should indicate what a check yields (which resources are alerting, current values vs. thresholds, or just a pass/fail) — it does not. For a simple read-only check tool this is a moderate gap rather than a fatal one, since annotations cover safety.

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 optional 'server' parameter is fully documented in the schema, so baseline 3 applies. The description adds nothing about the local-vs-remote execution difference beyond what the schema already states.

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

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

Specific verb+resource: 'Check resource alerts for CPU, memory, and disk usage against configured thresholds.' An agent can distinguish this from backup/docker/system_status siblings. However it never names the closest siblings (alerts_history, watch_check) 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?

Usage is only implied: the trailing clause about 'a running watcher' hints this is a one-shot check rather than a continuous watcher, but that phrasing is garbled and no alternative tool (alerts_history, watch_check, notify_test) is named. An agent must infer that this returns current state while alerts_history covers past alerts.

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

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

Annotations already cover the read-only, non-destructive profile, and the description adds a genuinely non-obvious behavioral fact: entries are only written while a watcher is running, so absence of data is not evidence of health. That is real value beyond the annotations. It omits any note on result volume, ordering, or time-range limits, so it is not fully transparent.

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

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

Two sentences, zero filler, with the core behavior stated first and the critical caveat immediately after. Nothing could be removed without losing information.

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

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

For a single-optional-parameter read tool with no output schema and annotations already declaring the safety profile, the description covers the main trap (interpreting an empty result). It does not describe what an entry contains or how much history is returned, which leaves a modest gap for an agent that must summarize results.

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

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

Schema coverage is 100% and there is only one optional `server` parameter already documented as 'runs locally if omitted'. The description adds nothing about how the remote server choice affects which history is returned — a meaningful omission, since history is presumably stored per host. Baseline 3 applies.

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

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

States a specific verb and resource ('Show recorded alert and remediation history'), which is more precise than a bare 'alerts' read. It does not explicitly distinguish itself from the nearby siblings `alerts` (current alerts) or `watch_history`, so an agent must infer the boundary between past recorded entries and live alert state.

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

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

Provides one strong interpretive guideline — an empty list means nothing was recording, not that nothing failed — but gives no explicit when-to-use versus `alerts` or `watch_history`. Usage context is implied by the word 'history' rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds real behavioral context beyond that — live volume reads can yield an inconsistent archive — but does not say what is overwritten on disk, whether existing archives are replaced, or what permissions/remote auth (server param) are required.

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

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

Two sentences, front-loaded with the verb and resource, and the second sentence is a dense but purposeful caveat plus routing hint. Nothing is redundant with the title 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 no-required-param tool with no output schema and fully documented params, the description covers the main hazard and the sibling routing. It leaves out where the archive lands by default and whether an existing archive at the destination is overwritten, which an agent might want before invoking a destructive tool.

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

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

Schema coverage is 100%, so the baseline is 3. The phrase "all services or one service" does clarify the default behavior of the optional service parameter (omission = all), which the schema does not state, but the to/server/exclude parameters get no additional meaning from the description.

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 first sentence gives a specific verb and resource ("Create a Docker compose backup archive") and the scope ("all services or one service"). It also implicitly separates itself from backup_drill by framing this tool as archive production rather than restore verification.

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

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

It explicitly names the sibling alternative (backup_drill) and the condition that selects it: an archive is not evidence it restores. It also gives the precondition/caveat for using this tool (volumes are read while containers run, so mid-write data can be inconsistent).

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

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

The description adds substantial behavioral context beyond the destructiveHint annotation: the drill runs a second copy beside the live app on its own network and port, and everything it creates is removed either way. It also clarifies that a pass means the archive is not corrupt and the app starts, not that every row is present. This makes the destructive annotation understandable and bounded.

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

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

The description is three front-loaded sentences with no wasted text. It first states the action, then explains the isolated execution model, then defines what a pass means. Each sentence earns its place by adding operational or interpretive value.

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

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

There is no output schema, so the description carries the burden of explaining the result, and it does so by defining what a pass means and what it does not mean. It also explains cleanup and isolation, which are key behavioral facts for this tool. It could go slightly further by describing failure output or confirming whether the live app is entirely untouched, but the definition is largely complete.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters, including the all/app relationship and the optional server and archive fields. The description does not add syntax or format details beyond what the schema provides. A baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description states a specific verb and resource: verify a backup by booting an app in an isolated Docker environment and checking that it responds. It clearly distinguishes this from backup_restore by framing the operation as a drill in a separate copy rather than a live restore. The added pass semantics further sharpen what the tool actually verifies.

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

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

The description implies when to use the tool: to verify that a backup archive is not corrupt and that an app can start on it. However, it does not explicitly compare it with siblings such as backup_restore or backup_list, nor does it state when not to use it. The usage is inferable but not fully guided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the important non-obvious caveat that listing is only metadata (names, sizes, dates) and is not evidence of a valid restore — a real behavioral limit not in structured data. Pagination or empty-directory behavior is not addressed, keeping it out of the 5 range.

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 what it does, then the caveat. No filler; every clause carries information the schema does not.

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

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

With no output schema, the description compensates by stating the returned fields (names, sizes, dates) and the semantic limit of those fields. Adequate for a simple one-parameter list tool; only the remote-server variant behavior is left implicit.

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 'server' parameter, so the schema fully documents it and baseline 3 applies. The description adds nothing about the local-vs-remote behavior or what 'configured backup directory' means per server.

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

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

States a specific verb+resource ('List existing backup archives') plus the location scope ('configured backup directory'), and explicitly separates itself from backup_drill. An agent can distinguish it from backup_drill, backup_create and backup_restore without opening any schema.

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

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

Names the alternative backup_drill and the condition that selects it: an archive's presence says nothing about restorability, so drill is the follow-up. It does not cover when to use backup_create or backup_restore, so the routing is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true, but the description adds what is actually destroyed (live app data is overwritten) and a policy constraint that will cause the call to be refused in some cases — genuine context beyond the annotation. It does not say whether the app is stopped first or what a partial restore looks like, leaving some behavior 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?

Three sentences, front-loaded with the destructive action before the safety instruction. Every sentence earns its place — no restatement of the name and no filler.

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

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

For a 3-parameter mutation tool with no output schema, the description covers the risky parts well. The remaining gap is outcome information — whether the app is restarted, whether restore is atomic, and how failures are reported — which an agent about to overwrite live data would benefit from.

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 (server, archive, service) are documented in the schema itself. The description adds no per-parameter meaning such as archive format expectations or service-selection semantics, 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 (restore) plus resource (Docker volumes from a backup archive) and its scope. It is immediately distinguishable from siblings like backup_create, backup_list, and backup_drill without opening any schema.

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

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

Gives a clear precondition — confirm intent before calling — and states a hard exclusion: bind mounts declared by the archive are always refused, with the reason given. It does not explicitly route to a sibling (e.g. backup_drill for safe verification), so it stops short of full when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the response is a diagnostic report covering which file and rule applied, per-section details, failures, and settings that were 'silently ignored' — the last being a noteworthy behavioral trait an agent would not otherwise know.

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

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

One well-built sentence that front-loads the action and then lists the return content in a compact, scannable sequence. No filler and nothing repeated from structured fields.

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

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

With no output schema, the description must indicate what comes back, and it does: the selected file, the selecting rule, per-section reads, and problems including silently ignored values. The only residual gap is that 'strict' behavior and any failure semantics are left to the 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 coverage is 100% and the single 'strict' parameter is fully documented in the schema as treating warnings as failures. The description says nothing about it, so the schema carries the full load — which matches the baseline of 3 for high coverage.

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

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

States a concrete verb and resource — checking the config file the server is running on — and enumerates exactly what is reported (file used, selecting rule, per-section reads, errors, silently ignored settings). It is far better than a tautology, though it never distinguishes itself from the sibling 'doctor' tool despite that one likely overlapping in diagnostic scope.

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

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

The usage is implied by the content — an agent would call this when debugging configuration behavior. There is no explicit statement of when to prefer this over 'doctor' or other diagnostic siblings, and no mention of any prerequisites or exclusions.

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

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

Annotations already declare this is a non-destructive read-only operation. The description adds useful behavioral scope beyond annotations by listing the categories returned and explicitly noting that environment variable values are never included, which matters for secret handling. It does not cover other operational details such as remote-server execution behavior, though the schema partially documents that 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?

The description is two sentences and front-loads the main purpose before adding the environment-variable exclusion. Every sentence adds useful information with no filler.

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

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

For a simple read-only inspection tool with fully described schema parameters and annotation-covered safety, the description is sufficiently complete: it lists what is summarized and discloses an important omission. It does not describe return structure, but there is no output schema, so that gap is minor rather than critical.

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 the container name and optional remote server are already documented in the schema. The description adds no parameter-specific syntax or semantics beyond the implicit single-container focus, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb, resource, and scope: it summarizes a single Docker container's image, state, restart policy, ports, mounts, networks, and health. This is clearly more specific than docker_list, but it does not explicitly name sibling tools or state how it differs from docker_stats, docker_top, or docker_logs.

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 the tool is for inspecting one container because it summarizes container details, but it does not state when to use it instead of docker_list, docker_stats, docker_logs, or docker_top. No exclusions, prerequisites, or alternatives are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: stopped containers are included, and a name appearing in the list does not guarantee it is running, so callers must read the state field. This is a useful disclosure beyond the annotations.

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

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

Two sentences, front-loaded with the core action and returned fields, followed by a critical caveat. There is no filler or redundancy.

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

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

For a simple read-only list tool with one optional parameter fully documented in the schema and no output schema, the description covers the essential behavior and the most important misinterpretation risk (stopped containers). Nothing critical is missing.

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

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

Schema description coverage is 100%, and the single optional 'server' parameter is fully documented in the schema. The description does not add any parameter-specific meaning, so it earns the baseline score for a fully-described schema.

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

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

The description states a specific verb and resource ('List Docker containers') and enumerates the returned fields (status, image, ports). It is clearly distinguishable from siblings like docker_inspect or docker_logs, though it does not explicitly name those 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?

Usage is implied: the tool is for listing containers, and the note about stopped containers clarifies an important scenario. However, there is no explicit guidance on when to use this versus docker_inspect, docker_stats, or other container-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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavior — non-streaming, default of 50 lines — but says nothing about whether stderr is included, timestamps, or truncation behavior, which matters for log retrieval.

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 resource and tacks on the two qualifying behaviors. Efficient, though the double clause structure is slightly dense compared with a clean two-sentence split.

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

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

For a simple read-only tool with no output schema and fully documented parameters, the description covers what an agent needs: what it returns, how much, and that it doesn't block on a stream. Remaining gaps (stderr, timestamps) are minor against this complexity.

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

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

Schema description coverage is 100%, so all three parameters (name, lines, server) are already documented in the schema. The description's mention of "50 by default" merely restates the schema default, adding no syntax or format detail beyond it — baseline 3.

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

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

States a specific verb and resource ("Get logs from a Docker container") and immediately scopes it to last N lines rather than a stream, which separates it from siblings like docker_inspect and docker_stats without needing their schemas.

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

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

The phrase "returns rather than following the stream" gives a clear usage condition and implicitly rules out a streaming-watch use case (which watch_check/watch_add cover). It stops short of naming an alternative tool explicitly, so it is not a full 5.

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

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

It discloses behavior annotations cannot express: the container goes down and comes back, and the success result reflects the command, not that the application inside is serving. That is exactly the caveat an agent needs to avoid over-reporting success. No contradiction with readOnlyHint=false/destructiveHint=false.

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

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

Three tight clauses with the purpose front-loaded, followed by the return-value caveat and then the prerequisite hint. The middle clause is somewhat wordy ('the result says the restart command succeeded, not that...') but that verbosity carries real information.

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

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

With no output schema, the description correctly spends its words on what the result does and does not mean, and annotations already cover the mutation profile. The only omission is the optional 'server' parameter's effect on execution locality, which the schema handles.

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 both the required 'name' and the optional 'server' are already documented in structured form. The description only reinforces the name-based targeting and says nothing about the remote-server option, so baseline 3 applies.

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

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

States a specific verb and resource — 'Restart a Docker container by name' — which is unambiguous against siblings such as docker_stop and docker_inspect. It does not explicitly name how it differs from docker_stop's stop/start cycle, keeping it 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?

'Read the logs first if you do not know why it needs restarting' gives a prerequisite workflow hint pointing toward diagnostic siblings. However, it never states when to restart versus docker_stop or proxmox_guest_reboot, so the primary selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results cover all running containers (implying no per-container filter and no output for stopped containers), but it says nothing about whether this is a one-shot snapshot or a sampled/streaming read, and gives no volume expectation for large host counts.

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

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

One sentence, front-loaded with the verb and the returned metric set, with zero filler. Nothing could be removed without losing information.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description usefully enumerates the returned metric families, which compensates for the absent output schema. The remaining gap is whether results are a snapshot or live samples, which matters for an agent building on the response.

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

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

Schema coverage is 100% and the single optional `server` parameter is already documented in the schema, including the local-run default. The description does not touch the parameter at all, which is acceptable given the schema, but adds nothing beyond it.

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

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

Specific verb ("Get") plus resource ("resource usage statistics") plus explicit metric categories and scope ("all running Docker containers"). It separates itself from docker_list/docker_inspect by naming metrics rather than container metadata, though it does not call out how it differs from the similar-sounding docker_top.

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

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

There is no when-to-use guidance, no exclusion of alternatives such as docker_top or docker_inspect, and no mention of what to do if a container is stopped. Usage has to be inferred entirely from the one-line purpose.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuinely non-obvious operational context beyond that: there is no start tool, so a stopped container must be revived out-of-band by the operator — useful for judging blast radius before calling.

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 padding, and the action statement is front-loaded ahead of the consequence note. Every clause contributes.

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

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

For a two-parameter mutation with full schema coverage and no output schema, this is nearly complete: action, target, and irreversibility are all conveyed. Minor gap — it doesn't say what happens if the container is already stopped or missing (error vs. no-op).

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

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

Schema description coverage is 100%, with both `name` (required) and `server` documented inline, so the schema carries the load. The description adds nothing about parameter handling — e.g. whether `name` must be exact, or how `server` changes targeting — so baseline 3 applies.

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

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

States a specific verb and resource ("Stop a Docker container") plus the addressing key ("by name"), which distinguishes it cleanly from siblings like docker_restart, docker_list, and docker_logs. An agent can select it from the tool list without opening the schema.

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

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

The description clarifies the terminal nature of the action but never names the obvious alternative: docker_restart exists and is the right call when the container should come back up. Usage is implied rather than routed, leaving the stop-vs-restart decision to inference.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations: it discloses that no exec/TTY is used, that commands are the kernel's truncated (<=15 char) 'comm' rather than the command line, and even the security rationale (avoiding leaking tokens passed on a command line). This is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loads the core action, then layers constraints and the truncation/security rationale. Every clause carries signal, though the final 'because...' rationale is slightly verbose for the space it occupies.

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, no-output-schema listing tool, the description covers the important behaviors (host-read, no exec, truncated comm) that an agent would otherwise get wrong. It doesn't describe the other returned fields (pid, user, etc.), a minor gap given no output schema exists.

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

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

Schema coverage is 100%, with both 'name' and 'server' clearly documented in the schema. The description adds no parameter-level meaning (e.g., name format, server config behavior) beyond what the schema already 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?

States a specific verb and resource ('List the processes running inside a Docker container') plus the critical scoping detail that it reads from the host. An agent can distinguish it from host-level 'processes' and from 'docker_stats'/'docker_logs' by the resource being container processes. It stops short of naming those siblings explicitly.

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

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

The description explains *how* it operates (read from host, nothing runs in the container) but never says *when* to choose it over 'processes', 'docker_stats', 'docker_inspect', or 'docker_logs'. No exclusions or alternative-selection guidance is provided, leaving routing to inference from the name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description echoes 'read-only', so safety is covered. It adds the scope of the sweep, but does not say whether findings are warnings vs errors, whether it changes any state, how long it takes, or how results are surfaced.

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 the key qualifier ('read-only') first and no filler. The comma-list of checked areas is dense but every item carries information.

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

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

For a multi-check diagnostic with no output schema, the description should say what the agent receives (a findings list? pass/fail summary? warnings?) and roughly what triggers a failure. It names the areas checked but leaves the result shape and severity model unstated, which matters for an aggregate tool.

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

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

Schema coverage is 100% with only two optional parameters, and the schema already explains the server target and the backup_max_age_hours default of 168. The description only indirectly hints at the backup-age threshold via 'backup hygiene', adding no syntax or interpretation guidance beyond the schema.

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

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

The description gives a specific verb ('Run a read-only diagnosis') and enumerates the exact domains checked: resource pressure, stopped containers, public ports, backup hygiene, notifications, and report baseline. That enumeration clearly separates it from focused siblings like docker_stats, open_ports, backup_list, or system_status, though it never explicitly names 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 only implied — an agent can infer this is a broad pre-flight/health sweep rather than a targeted query. There is no statement of when to prefer it over report, system_status, or running individual checks, and no prerequisites are mentioned.

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

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

Annotations already signal destructiveHint=true, and the description adds genuinely useful behavior: automatic pre-checks for docker/ports/duplicates and the key fact that refusals return as results rather than errors. It also discloses a 'warning' outcome when leftover Docker volumes exist. It stops short of stating permission requirements or what a successful result contains, keeping it at 4.

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

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

Front-loaded with the core action in the first sentence, and every subsequent clause (pre-checks, refusal-as-result, warning) earns its place. The trailing warning clause is slightly fragmentary but still dense with signal.

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

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

With no output schema, the description compensates by explaining refusal and warning semantics, which is exactly what an agent needs to interpret results. It lacks detail on success output and permissions, but for a two-parameter install tool it is largely complete.

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

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

Schema coverage is 100%, so both parameters (app, port) are already documented, and the description adds no additional meaning such as port conflict behavior or accepted app name formats. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Install a self-hosted app via docker compose'), which cleanly separates it from siblings like install_uninstall, install_purge, and install_status. An agent can identify this as the creation step of the install lifecycle without opening the schema.

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

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

The description implies usage (install an app) and explains that pre-checks happen automatically, but never explicitly says when to choose this over install_uninstall, install_purge, or install_status. No exclusion or prerequisite guidance is given beyond the implicit lifecycle ordering.

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

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

The annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the catalogue is compiled into the binary, requires no network, and returns consistent results across machines.

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

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

The description is two tightly written sentences with no wasted wording. It front-loads the core purpose and then adds a relevant operational note.

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

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

For a zero-parameter catalogue list, the definition is largely complete: it explains what is listed and confirms offline deterministic behavior. It could additionally clarify what the returned list contains or how it relates to install_app, but those are minor gaps given the simple interface.

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

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

This tool has zero parameters, so there is no parameter semantics to document. The input schema is empty and fully consistent with the description.

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

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

The description uses a specific verb and resource: list available self-hosted apps that can be installed. That scope clearly distinguishes it from install_app, install_status, install_uninstall, and the other install-* siblings.

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

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

The intended use is implied: call this to discover installable apps. However, it does not explicitly say when to use this versus install_status or when to proceed with install_app, and it names no exclusions.

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

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

Annotations already mark this as destructive, but the description adds irreversibility, the fact that no backup is taken automatically, and post-call volume reporting via kept_volumes and unchecked_volumes. This goes well beyond structured annotations.

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

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

Front-loads the destructive action and immediately follows with the irreversible consequence and backup warning. Three tight sentences, and the kept_volumes/unchecked_volumes caveat also 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 destructive mutation with no output schema, it covers data loss, backup requirements, and partial return behavior. Together with the destructive annotation, an agent has enough context to call it safely.

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 only one required parameter, app, and schema coverage is 100% with 'App name'. The description refers to an 'installed app' but adds no syntax or format semantics beyond the schema.

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

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

States a specific action—stop and delete all data including containers, config, and volumes—for an installed app. It is clearly destructive and more complete than a generic uninstall, though it does not explicitly name install_uninstall as the non-destructive sibling.

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

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

Provides an explicit prerequisite: take a backup before calling if the data matters. It does not explicitly contrast install_uninstall or give a when-not-to-use condition beyond the data-loss warning.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that — the status is a container-reported view and unmanaged apps are unknown — but does not say what happens for an unknown app name (error vs. empty) or what status values look like.

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

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

Two short sentences, front-loaded with the core purpose. The second sentence is terse to the point of being slightly cryptic ("is not known here"), but nothing is wasted.

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

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

A simple read tool with annotations and no output schema, so the bar is low, but the description never characterizes what a "status" result contains (running/stopped/degraded, per-container vs. aggregate) — the one thing an agent needs to interpret the response of a status 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?

Only one parameter, and the schema documents it at 100% coverage ("App name"). The description adds no further meaning such as accepted name formats or whether the app must match an install_list entry, so baseline 3 applies.

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

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

States a specific verb and resource ("check the status of an installed app") and adds the qualifier that the status comes from containers. It is distinguishable from install_list (enumerate) and docker_inspect (raw container detail), though it never names those siblings explicitly.

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

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

The second sentence gives an explicit when-not condition: apps not installed by homebutler are invisible here, which routes the agent away from this tool for foreign apps. It stops short of naming an alternative tool (e.g. install_list or docker_inspect) for those cases.

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

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

Annotations already flag destructiveHint=true, yet the description adds meaningful detail: containers are removed while the app directory and volumes remain on disk, and it explains the 'warning' signal's meaning (state stranded in Docker volumes from an earlier install). That is exactly the beyond-annotation context an agent needs before a destructive call.

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

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

Three tight sentences, front-loaded with what happens, then what is preserved, then the alternative. Every sentence earns its place 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?

For a destructive single-parameter tool with no output schema, the description covers the action, the preservation boundary, the sibling alternative, and even the semantics of a returned warning. Nothing needed to call it safely is missing.

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

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

There is a single parameter ('app') with 100% schema description coverage, so the schema carries the semantics. The description adds no format or constraint details beyond the schema, which is 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+resource: 'Stop an installed app and remove its containers'. It immediately scopes what is removed versus kept, which distinguishes it from siblings like install_purge and docker_stop.

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

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

Explicitly routes the agent to the alternative: 'install_purge is the one that deletes them', giving a clear selection condition. It does not distinguish from other stop-like siblings (docker_stop), but the main ambiguity is resolved.

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

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

Annotations already declare the operation non-destructive and read-only, so the bar is lower. The description adds the meaningful constraint that one format is local-only while the other works remotely, which is behavioral context not fully spelled out elsewhere. It does not mention that a local export writes a file to disk or where that file lands, which is the main remaining 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 verb and resource come first and the format/locality constraints follow 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 two-optional-parameter export tool with no output schema, the description covers formats but omits where local artifacts are written and what the JSON payload represents. An agent can call it, but not predict the result with confidence.

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

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

Schema coverage is 100% and both parameters are already documented with their defaults and the remote/json constraint. The description restates the format split without adding syntax, valid values beyond what the schema says, or path semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (export) and resource (server inventory/topology), plus the two output formats. It is clearly distinguishable from the sibling inventory_scan, but it never names a sibling or explicitly draws that contrast.

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 the routing decision by pairing 'Mermaid ... locally' with 'JSON locally/remotely', so an agent can infer that Mermaid cannot be used against a remote server. However, it never says when to export at all, whether a scan must run first, or what to do when both options are viable.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the collection scope, but says nothing about cost/latency of scanning a remote host, output format, or whether results are persisted.

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 an explicit list of collected data; nothing is wasted. It is short to the point of leaving routing and behavioral details out, but structurally sound.

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

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

With no output schema, the enumeration of collected categories partially substitutes for a return description, which is useful. However, an aggregation tool with many overlapping siblings needs more routing context than is provided to be called correctly.

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

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

Schema coverage is 100% and the single optional `server` parameter is fully documented there, including the local-fallback behavior. The description adds no parameter-level meaning, 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?

"Collect server inventory/topology" is a specific verb+resource, and the enumerated contents (system status, Docker containers, app ports, system ports) make the scope concrete. It does not differentiate itself from siblings like system_status, docker_list, open_ports, or inventory_export, which cover overlapping ground.

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 aggregating scan versus the narrower sibling tools (system_status, docker_list, open_ports) or inventory_export. The only usage-like fact (local vs remote) lives in the schema, not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not obligated to cover safety. It does add real behavioral context beyond the annotations: it probes every address on the subnet and can take up to 30 seconds, which is exactly what an agent needs to decide whether to wait on this call. It omits any mention of required network access or privileges.

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

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

Two sentences, front-loaded with the verb and returned fields, and the latency warning is placed where it will be read. The second sentence drifts into an awkward metaphor ('a question somebody asked rather than a way to begin') that costs clarity without adding much information.

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

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

With no parameters, no output schema and read-only annotations, the description carries the remaining burden well: it names the returned fields and discloses the 30-second worst-case duration. It stops short of saying what happens on unreachable subnets, whether results are cached, or what error conditions to expect.

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

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

The tool takes zero parameters, so the baseline is 4. The description's mention of the subnet scope is the closest thing to a parameter note, and nothing more is needed.

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

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

States a specific verb and resource ('Scan the local network to discover devices') and even names the returned fields (IP, MAC, hostname). It does not distinguish itself from close siblings like inventory_scan or open_ports, which also deal with network/host discovery, so an agent must infer the boundary.

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

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

The trailing clause ('an answer to a question somebody asked rather than a way to begin') gestures at when to use it, but the phrasing is garbled and only implies the guidance rather than stating it. No sibling alternatives (inventory_scan, open_ports) are named as the better choice in any situation.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the bar is lower, yet the description adds the crucial side effect that a real message is delivered to each channel and visible to channel readers. That is exactly the kind of non-obvious consequence an agent needs before invoking. It stops short of mentioning throttling, duplicate sends, or what happens when a channel fails.

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, with the action and its scope front-loaded and the warning about real message delivery immediately following.

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

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

No output schema exists, and the description indicates the return content ('report which ones arrived'), plus discloses the external side effect. For a zero-required-parameter tool this is nearly complete, missing only failure-mode or prerequisite detail.

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 optional 'server' parameter, so the schema already carries the semantics. The description adds nothing about the server-vs-local behavior, leaving the schema to do all the work; 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 and resource: sends a test notification through every configured channel and reports delivery results. The word 'test' distinguishes it from the real alerting siblings (alerts, watch_add), though no sibling is named explicitly.

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

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

The purpose implies the use case (verifying that notification channels are working), but the description never states when to prefer this over doctor or alerts, nor any exclusions or prerequisites such as requiring channels to be configured first.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: process attribution can fail without privilege, and the result signals this via a missing_process field rather than an empty value — context an agent cannot get from annotations or schema.

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

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

Two sentences, the purpose front-loaded in the first, and the second dedicates itself to one useful semantic caveat about missing_process. Slightly awkward phrasing ('says so rather than leaving the field quietly empty') but nothing is wasted.

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

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

A read-only list tool with one optional parameter and no output schema is well served by stating what is returned (ports plus process info) and how unreadable process data is represented. Only the broader shape of the result set (sorting, scope, pagination) is left implicit, which is minor here.

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

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

Schema description coverage is 100% and there is only one optional parameter, so the schema fully documents 'server' and the local-default behavior. The description adds no further meaning about that parameter, 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?

Names a specific verb and resource — 'List open network ports' — plus the payload qualifier 'with associated process information'. It is distinguishable from most siblings, though it never says how it differs from network_scan or processes, which an agent would have to infer.

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 network_scan, processes, docker_top, or system_status, and no preconditions or exclusions. The only scoping hint ('runs locally if omitted') is already carried by the schema, so the agent gets no routing guidance from 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return content: a total count and zombies broken out separately, which is important given there is no output schema and no other source for return shape.

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

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

A single well-formed sentence with zero padding, front-loading the action and resource before the output details. Nothing is wasted or repeated.

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

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

For a simple three-parameter read tool with full schema coverage and read-only annotations, the description covers purpose and return shape adequately. It omits any note on remote-vs-local behavior via the server parameter and on how 'top' interacts with limit=0, which are the only notable gaps.

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

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

With 100% schema description coverage, the schema already documents limit, server, and sort_by fully. The description only echoes the sort dimension ('CPU or memory') and adds no syntax, defaults, or server/local semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List the top processes') plus the two sort dimensions (CPU or memory). An agent can tell what it returns, though it does not differentiate itself from nearby siblings such as docker_top or system_status.

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

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

The description gives no when-to-use guidance, no exclusions, and no pointer to alternatives like docker_top for container processes or system_status for host overview. The agent must infer selection from the tool name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds the important async behavior that the call returns an accepted task UPID rather than completing synchronously, which tells the agent to poll for status. It does not mention the service interruption a reboot causes, leaving a small gap for a disruptive operation.

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

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

A single front-loaded sentence with no waste: the action, the targeting constraint, the confirmation prerequisite, and the return value all appear in one compact statement.

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

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

With no output schema, the description correctly specifies that an accepted task UPID is returned, which is what the agent needs to know. It could have pointed to proxmox_task_status for polling and noted the downtime implied by a reboot, but nothing required is missing.

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

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

Schema coverage is 100%, so endpoint, node, type, vmid and confirm are all documented in the schema itself. The description only reinforces the explicit-targeting framing and does not add format or edge-case 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?

States a specific verb (reboot) and a precisely scoped resource (one explicitly targeted Proxmox guest), plus the confirmation gate and return value. It is immediately distinguishable from sibling power tools like proxmox_guest_shutdown and proxmox_guest_start.

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?

"One explicitly targeted" and "after confirmation" convey the conditions for correct invocation, implying the caller must identify a single guest and set confirm. It stops short of naming the alternative tools (shutdown/start) or stating when not to reboot, so it is clear context but not full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that all four filters are optional (i.e., an unfiltered call returns everything), which is useful, but says nothing about result volume, ordering, or whether the call fans out across endpoints/clusters.

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 the action and resource front-loaded and the filter scope trailing. No filler, no 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 zero-required-parameter read-only list tool with full schema coverage and annotations covering safety, this is nearly complete. The only missing piece an agent might want is how the endpoint parameter resolves when omitted and whether the response carries guest type/node, but the complexity is low enough that this is a minor gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the qemu/lxc and running/stopped value hints. The description restates the same three filters and never mentions the fourth parameter (endpoint) or the 'optional when exactly one is configured' fallback behavior, so it adds no meaning beyond the schema.

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

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

States a specific verb (List) and a precise resource (Proxmox QEMU and LXC guests) plus the available filter dimensions. It is distinguishable from the mutation siblings (guest_start/shutdown/reboot) and from proxmox_node by resource, though it never names an alternative explicitly.

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

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

The phrase 'optionally filtered by node, status, or type' implies the retrieval use case, but there is no statement of when to prefer this over proxmox_node, proxmox_status, or proxmox_guest_* siblings, and no exclusions. Usage is inferable rather than guided.

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

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

Annotations already declare destructiveHint=true, so the safety bar is partly covered; the description still adds real value by specifying the shutdown is graceful (ACPI-style, not a hard kill) and that the call returns an accepted task UPID rather than a final result. It does not mention that a guest ignoring the signal may not power off, which would be the remaining 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 sentence with no filler, front-loading the action, the scope constraint, and the return value in that order. Every clause carries information.

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

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

No output schema exists, and the description compensates by stating the return is an accepted task UPID, which tells the agent the operation is asynchronous. It stops short of saying the agent should poll proxmox_task_status to confirm completion, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters including the confirm flag and the type enum are already documented. The description only reinforces that the target must be explicit and confirmed, adding no format or value details beyond the schema — the baseline 3 for full coverage 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 pair ('Gracefully shut down one ... Proxmox guest') with an explicit scope qualifier ('one explicitly targeted'). The verb itself separates it from proxmox_guest_reboot and proxmox_guest_start, but the description never names those siblings to close the loop.

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?

'after confirmation' and the required confirm flag imply the precondition for calling, but the description never says when to prefer this over a forced stop or over proxmox_guest_reboot. Usage is inferable from the verb rather than stated.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) are consistent and already cover the safety profile. The description adds real value beyond them by disclosing that the call is asynchronous — it returns an accepted task UPID rather than the final power state — which is non-obvious for a start operation.

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

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

One sentence, zero filler, with the target-scope and confirmation constraints front-loaded before the return behavior.

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

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

With five required params and no output schema, the description must carry return semantics, and it does by naming the accepted task UPID. It stops short of telling the agent to poll proxmox_task_status for completion, which is the one piece an agent still has to infer.

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 five parameters are documented in the schema; baseline is 3. The description reinforces the targeting semantics of the confirm flag but adds no format or constraint detail beyond what the schema already provides.

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 (Proxmox guest) with a scope qualifier ('one explicitly targeted guest'), which cleanly separates it from proxmox_guest_shutdown and proxmox_guest_reboot. It never names those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

'after confirmation' and 'explicitly targeted' imply the precondition for calling, but there is no explicit when-to-use/when-not guidance and no pointer to the stop/reboot alternatives. Usage is suggested rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, but the description contributes nothing further — it does not say what "detailed" comprises, whether it contacts the node live (latency/failure modes), or what happens if the node is unreachable. The word "detailed" is the only behavioral hint and it is undefined.

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

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

A single short sentence that is front-loaded and wastes no words, which is good, but the brevity comes at the cost of under-specification rather than genuine economy. There is room for one clarifying clause without bloat.

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

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

No output schema exists, so the description carries the burden of conveying what a "detailed status" response contains — and it says nothing. For a read tool whose entire value is the returned payload, the agent has no idea what fields or shape to expect.

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

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

Schema description coverage is 100%, so both parameters (node, endpoint) are fully documented in the schema, including the optional-when-single-endpoint nuance. The description adds no meaning beyond that, 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 verb and resource ("Get ... Proxmox node status"), so the basic action is clear, but "detailed" is undefined and nothing distinguishes this from the sibling proxmox_status or proxmox_guests. An agent cannot tell from the text alone whether this returns host metrics, services, or guest inventory.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. node must be in the endpoint config), and no routing to alternatives such as proxmox_status or proxmox_guests. The agent must infer selection from the name alone.

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

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

Annotations already declare a safe read-only, non-destructive operation; the description adds genuinely new behavioral context by stating it never fetches or runs the command and that execution is the caller's responsibility. It doesn't specify the rendered output shape (e.g., a single curl|bash line), which keeps it short of a 5.

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

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

Two compact clauses, front-loaded with the core action, and the safety disclaimers follow immediately. No filler or restated title.

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

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

For a single-parameter read tool with no output schema and full schema coverage, the description covers purpose and safety adequately. A brief note on what the rendered string looks like (or that it is inert text meant for copy-paste) would close the remaining gap.

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

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

Schema coverage is 100% and the slug parameter's description already gives the source tool and an example ("docker"). The prose adds only that the command belongs to "one" script, so the schema does the heavy lifting — baseline 3.

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

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

Specific verb ("Render") plus specific resource ("the pinned install command for one Proxmox VE Community Script"), and the second clause clarifies what it does NOT do. It doesn't explicitly name proxmox_script_list as its upstream sibling in the description body (that link lives only in the schema), so sibling differentiation is slightly incomplete.

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 caller reviews and runs it themselves on the Proxmox host" implies the usage context — you fetch text rather than trigger an install — but there is no explicit when-to-use/when-not or named alternative (e.g., install_app for actual execution is only inferable from the sibling 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the catalog is curated and sourced from community-scripts/ProxmoxVE, but it does not describe return shape, pagination, or how the catalog relates to execution tools. With annotations carrying the main behavioral burden, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no wasted words. The verb and resource appear immediately, and the repository reference is compact supporting detail.

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

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

For a zero-parameter catalog-listing tool whose annotations already establish read-only behavior, the description is nearly complete. A small gap remains: it could connect the catalog to proxmox_script_command or explain that this is the discovery step before script execution.

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

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

The tool takes zero parameters, so the parameter-semantics baseline is 4. There are no arguments whose meaning the description needs to clarify.

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 ('List') and resource ('curated Proxmox VE Community Scripts catalog') and names the upstream repository. It is clear what the tool does, but it does not explicitly distinguish itself from nearby siblings such as proxmox_script_command or install_list.

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

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

There is no explicit guidance on when to use this tool, when not to use it, or which sibling to use instead. An agent can infer that it is for browsing available scripts, but that inference is not supported by stated alternatives 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns version, cluster status, and resources, but does not add deeper behavioral context such as authentication requirements, limits, or return format.

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

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

A single compact sentence that front-loads the key information with no wasted words.

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

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

For a simple read-only status tool with full schema coverage and no output schema, the description is largely complete: it names the main data categories returned. It could be slightly stronger by clarifying the relationship to sibling Proxmox inspection tools.

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

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

Schema description coverage is 100%, so the single optional endpoint parameter is already fully documented. The description adds no additional parameter semantics beyond what the schema provides, 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?

States a specific verb and resource: get Proxmox VE version, cluster status, and resources. It is clear what the tool does, but it does not explicitly distinguish itself from proxmox_guests, proxmox_node, or proxmox_tasks, which cover related Proxmox data.

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

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

The description implies usage for an overall Proxmox VE status overview, but gives no explicit when-to-use guidance, exclusions, or alternatives such as proxmox_guests or proxmox_node. The intended context is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful 50-result cap and node scoping, but says nothing about ordering guarantees, task states returned, or whether results can be paged beyond 50.

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 waste; the result cap and node scoping are both conveyed 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?

For a read-only listing tool with fully documented parameters and no output schema, the description covers the essential scope and result limit. It could note what a task record contains or whether status filtering is possible, but nothing critical for a correct call is missing.

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

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

Schema description coverage is 100%, so both node and endpoint are already documented in the schema. The description adds no format details or constraints for either parameter, 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?

States a specific verb (Get) and resource (Proxmox tasks) with explicit scope: 50 most recent, filtered by node. It is distinguishable from the sibling proxmox_task_status by name, though the description does not explicitly contrast the two.

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

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

Usage is implied — list recent tasks for a node — but there is no explicit guidance on when to prefer this over proxmox_task_status or proxmox_status for individual task details or broader node status. The agent must infer the boundary from tool names alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the task is asynchronous and keyed by an opaque UPID, but it does not describe return details such as task state, exit status, or log availability.

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. It is appropriately sized for a simple read-only inspection tool.

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

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

For a low-complexity read-only status tool with full parameter schema coverage and safety annotations, the description is enough to select and invoke it correctly. It could mention what the inspected status contains, but that is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema. The description repeats node and opaque UPID but adds no syntax or format meaning beyond the schema, and does not mention endpoint; the baseline 3 is appropriate.

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

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

States a specific verb (Inspect) and resource (one asynchronous Proxmox task) scoped by node and opaque UPID. It implicitly contrasts with the sibling proxmox_tasks list tool, though it does not name that alternative.

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

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

Usage is implied: inspect a single task when you already have its node and UPID. It does not explicitly say when to use this versus proxmox_tasks or other Proxmox tools, nor does it state any exclusions.

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

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

Annotations mark this as non-read-only and destructive; the description adds meaningful context by disclosing that it saves a snapshot unless no_save is set, shifts the comparison window, and can undermine future comparisons in a loop. It does not explicitly explain snapshot pruning/retention via keep or what exactly is destroyed when old snapshots rotate out, so 4 rather than 5.

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

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

Two sentences, front-loaded with purpose and then the critical side-effect caveat. There is no redundant restatement of schema or annotations.

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

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

For a tool with no output schema, it names the report's components and the key persistence/no_save behavior needed to call it correctly. Remaining parameter details are fully covered by the 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 the baseline is 3. The description adds real meaning for no_save—that skipping the write moves the comparison window—but says nothing extra about keep or server beyond what the schema already documents.

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 ('Generate') and resource ('health report') and lists its contents: snapshot comparison, warnings, notable changes, and suggested actions. It does not explicitly differentiate this from siblings such as doctor or system_status, so it falls short of a 5.

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

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

It implies use for health reporting and warns that repeated calls in a loop can leave nothing to compare against, but it never states when to choose this tool over doctor/system_status or explicitly when to prefer no_save. The guidance is present but mostly inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: that inside a container the reported metrics describe the container, not the host, which prevents a common misinterpretation of the returned numbers. It does not disclose how remote vs local execution affects results.

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

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

Two short sentences, zero filler. The metric list comes first and the scoping caveat follows as a qualifier, which is the right order for an agent skimming for capability before semantics.

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

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

For a read-only, zero-required-parameter status tool with no output schema and full schema coverage, the description tells the agent what metrics come back and what the scope caveat is. The only minor gap is not stating how the remote `server` mode differs in result shape or latency.

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 `server` parameter is documented there, including the local-if-omitted default. The description reinforces the local scope but adds no syntax, naming format, or failure behavior for the remote case, so 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?

Specific verb (Get) plus resource (system status) and an explicit enumeration of the returned metrics: CPU, memory, disk usage, uptime. The second sentence scopes the resource to 'the machine this binary runs on', which cleanly separates it from siblings like docker_stats and proxmox_status that report on other layers.

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 container-vs-host caveat implies a usage context, so an agent can infer when this tool is appropriate rather than docker_stats or proxmox_node. However, no sibling is named and there is no explicit statement of when to prefer the remote `server` parameter over a local run or over the Proxmox/Docker alternatives.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining outcome semantics — and it does so well by clarifying that success means the packet was sent, not that the host woke. It stops short of noting prerequisites like broadcast/subnet reachability or that the target must be on the local network segment.

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 action and followed by the critical caveat. Every clause earns its place with no repetition of schema or annotations.

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

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

For a simple two-parameter tool with no output schema, the description supplies exactly the missing piece — what a successful return actually means. Combined with annotations covering the safety profile, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so both parameters (target, broadcast) are already documented including the default broadcast address. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Send a Wake-on-LAN magic packet') and resource ('a machine'), which is unambiguous and clearly distinct from sibling start tools like proxmox_guest_start. An agent can identify the tool's job 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 specificity of the action — you'd only call this to wake a machine — but the description never states when to prefer it over siblings such as proxmox_guest_start or when it will fail (e.g., cross-subnet). No explicit alternatives or exclusions are offered.

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

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

Goes well beyond readOnlyHint=false/destructiveHint=false by disclosing that the write is list-only with no side effect on monitoring, that supervisor installation is out of scope, and that duplicate adds return added=false rather than erroring. These are exactly the behavioral facts an agent cannot infer from annotations.

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

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

Three sentences, each doing distinct work: what it does, what it does not do, and the duplicate-add semantics. Front-loaded with the action, 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?

No output schema exists, yet the description explains the meaningful return outcome (added=false). For a simple list-mutation tool with full param coverage and declared safety hints, nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so kind, unit, server, and container are already documented. The description restates that container/unit/app are the same slot but adds no syntax, format, or default detail for server or unit 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 and resource — 'Add a Docker container, systemd unit, or PM2 app to the watch list' — which immediately separates it from watch_remove, watch_list, and watch_history. It does not explicitly name a sibling alternative, so it falls just short of the top mark.

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 line 'nothing begins watching it — a supervisor has to be installed separately' sets a clear expectation for when this tool alone is sufficient and when install_list or doctor is needed. No explicit instruction to prefer a named sibling, but the context is unambiguous.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, but the description frames the tool as a 'check' and 'report' without explaining what is destructive or what state is changed. The phrase 'since the last check' hints at state tracking, but the destructive nature is not disclosed, leaving a critical gap for a mutation-flagged tool.

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

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

The description is two sentences, front-loads the primary action, and adds the target-type caveat without unnecessary detail. Every sentence contributes useful information.

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

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

For a single-parameter check tool with annotations and no output schema, the description covers the core purpose and target-type behavior. It is incomplete because it does not reconcile the 'check' framing with the destructive annotation, leaving the agent without crucial behavioral context.

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

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

Schema description coverage is 100% and there is only one optional parameter ('server'), so the schema already carries the parameter semantics. The description does not add meaning beyond what the schema provides, making the baseline score 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 ('Run a one-shot restart check') and resource ('watched targets'), and it clarifies what is reported ('restarts detected since the last check'). It does not explicitly distinguish itself from sibling tools like watch_history or watch_list, so it falls short of the top score.

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

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

It gives a clear usage context for a one-shot check and adds an important target-type limitation: only docker targets are inspected, while systemd and pm2 are reported as skipped rather than assumed healthy. It does not name alternative tools or state when to prefer them, so it lacks full 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?

With readOnlyHint and destructiveHint already declaring a safe read operation, the description adds valuable behavior beyond annotations: results are newest first, and captured logs are excluded by default due to their volume. It does not cover return shape, but the annotation burden is already low.

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

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

Two sentences, front-loaded with the core action and ordering, followed immediately by the important default exclusion behavior. There is no filler or repetition.

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

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

For a read-only list tool with full parameter documentation and no output schema, the description covers ordering, default log exclusion, and the reason for that default. It could be improved by briefly indicating the incident fields or total-count behavior, but it is otherwise 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 four parameters are already documented. The description adds practical rationale for include_logs specifically, but does not elaborate on limit, server, or container beyond the schema.

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

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

The description clearly states a specific verb and resource: 'List recorded restart incidents, newest first.' It distinguishes this from general watch management tools by focusing on incident history, but it does not explicitly name its sibling alternatives such as watch_list or watch_check.

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

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

It gives useful conditional guidance for include_logs, explaining that logs are excluded by default because each incident carries a hundred lines of output twice over. However, it does not state when to use this tool versus watch_list, watch_check, or other watch-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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that each entry includes its kind and last recorded check result, but says nothing about ordering, empty state, or whether the 'last check' may be stale.

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 packs the return-field hint with zero filler. Nothing is wasted.

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

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

For a simple, annotation-backed read tool with no output schema, the description conveys the action and the shape of the results. Only minor gaps remain (ordering, freshness of 'last check'), which are not essential to calling 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?

There is only one optional parameter and the schema documents it at 100% coverage, including the local-versus-remote behavior. The description adds nothing about the server 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?

A specific verb ('List') plus a clear resource ('targets being watched') and supplementary detail on the returned fields ('kind' and 'last check recorded'). An agent can distinguish it from watch_add/watch_remove/watch_check, though it never explicitly names 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 by the nature of a list operation, but there is no explicit statement of when to choose this over watch_check (which presumably performs a check) or watch_history. The agent must infer the role from the name.

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

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

Annotations declare destructiveHint=true and readOnly=false; the description adds the crucial qualifier that the destruction is limited to the list entry — recorded incidents are preserved and whatever was supervising the target keeps running. That refines the blast radius in a way the annotations cannot express, though it does not cover error behavior (e.g. name not currently watched).

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

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

Two short sentences with the primary effect first and the clarification second; every clause carries information 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 two-parameter mutation with no output schema and full annotation coverage, the description supplies the one non-obvious fact an agent needs — that removal is not the same as stopping supervision. Only the outcome when the target is absent from the list is left unaddressed.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the optional remote-server scope and the local fallback. The description adds no format, matching, or identifier-syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Remove a target from the watch list") and immediately scopes what removal means. It is clearly distinguishable from watch_add/watch_list/watch_history by implication, though no sibling is named explicitly.

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

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

Usage is implied — you call it to stop watching a target — but there is no explicit when-to-use/when-not guidance and no mention of alternatives for temporarily muting versus permanently unwatching. Adequate but leaves routing to inference.

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