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

With no annotations, the description carries the full burden and does well: it declares read-only enforcement, that credentials are sourced from .env and never returned, and that rows are capped by limit. It omits query error behavior and the fact that it can target any project dir within the allowed roots, but the key safety and auth traits are disclosed.

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

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

Three tight sentences, front-loaded with the operation and its read-only constraint, then credentials handling, then the row cap. Every sentence carries distinct 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?

No output schema exists, but the return shape is largely self-evident for a query tool (result rows from the SELECT), and the credential/row-cap notes cover the main surprises. It is nearly complete, though it could state the result envelope or error signaling.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with defaults and bounds. The description only restates the limit cap ('Rows capped by limit') and adds nothing about timeout_secs or the project_dir allowlist, 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?

Specific verb ('Run') plus precise resource ('READ-ONLY SQL query against a Laravel project's database') with an explicit scope constraint (SELECT/WITH). No sibling tool operates on a database, so an agent can immediately tell this apart from read_file or run_command.

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 read-only SELECT/WITH restriction implies the intended use case, but there is no explicit statement of when to reach for this versus alternatives such as run_command or reading files. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the operation is read-only and that results cover all mounts and top-level directories, which is useful. However, it does not explain permission requirements, output size limits, or potential latency across mounts, leaving gaps for an agent.

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

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

A single, compact sentence that front-loads the core purpose and appends key output scope and safety qualifier. Every element earns its place with no redundancy.

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

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

For a read-only diagnostic tool with no output schema and no annotations, the description is minimal but serviceable. It covers the main output dimensions, yet lacks return format details or hints about potential host-specific differences. It is adequate but could be more 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% for the single host parameter, so the schema already fully documents it. The description adds no parameter details, but baseline for one fully described parameter is 4 since there is little to compensate for.

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 resource (disk usage) and the exact output scope: all mounts plus largest top-level directories. 'read-only' further distinguishes it from mutating siblings like edit_file or run_command. It does not explicitly contrast with system_info, which may be a sibling that also reports host metrics.

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 should be used for disk-space inspection via 'disk usage', but it offers no explicit when-to-use/when-not-to-use guidance nor names an alternative for disk-related queries. The omission of host via the schema is the only usage cue.

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

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

With no annotations, the description carries the behavioral burden. It usefully states that the operation is read-only, which is the key safety trait, but it does not describe error behavior, remote-host implications, or output characteristics beyond what the schema already encodes.

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

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

The description is a single front-loaded sentence with no filler, so it is easy to scan and every word contributes to identifying the tool's action and target.

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 full schema parameter coverage and no output schema, the description is largely complete. It identifies the operation and safety profile; only minor return-value context 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 three parameters (host, tail, container) are already well documented in the input schema. The description adds no parameter-level meaning beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Read recent logs of a Docker container'), so the agent knows exactly what the tool returns. It does not explicitly contrast itself with siblings such as docker_stats or read_file, which keeps it from a 5.

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

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

The intended use is implied: inspect recent container logs. There is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives, and no prerequisites, so it is only minimally adequate.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It does disclose that the operation is read-only and analogous to 'docker ps', which is valuable. However, it omits details such as permissions needed, output format, or behavior when no containers exist.

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

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

A single efficient sentence with no wasted words. The read-only hint is front-loaded and the analogy is compact.

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 list tool with one optional, fully documented parameter and no output schema, the description provides adequate context to invoke it correctly. It lacks usage guidance and richer return-value hints, but the core information is present.

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

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

Schema description coverage is 100%, so the single 'host' parameter is already fully documented in the schema. The description adds no additional parameter meaning, making the baseline of 3 appropriate.

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

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

States a specific verb (list) and resource (Docker containers) plus what is included (status). The 'like docker ps' analogy makes the scope clear. However, it does not explicitly differentiate from sibling tools such as docker_stats, which also concerns containers.

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

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

No guidance on when to use this tool versus alternatives like docker_stats or docker_logs. The description only states what it does, not when an agent should choose it.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses two things annotations would otherwise supply: this is a mutating write action and the MCP client will prompt for approval. It omits operational behavior such as whether the restart is graceful, what happens if the container is stopped or missing, and whether dependent services are affected.

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, with the destructive/prompt-worthy nature front-loaded after the core action. Nothing could be cut 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 two-parameter tool with a fully documented schema and no output schema, the definition covers purpose, mutating nature, and approval behavior. Missing only failure/edge-case behavior (container not running, name not found), which is a minor gap at this complexity level.

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

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

Schema description coverage is 100%: both 'host' (with HOMELAB_HOSTS semantics and local-machine default) and 'container' are fully documented in the schema. The description adds nothing about parameters, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Restart a Docker container'), instantly distinguishable from read-only siblings like docker_ps or docker_logs. It does not name any sibling explicitly, though the schema's 'from docker_ps' hint covers that on the parameter side.

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 'WRITE action' framing implies when this tool is appropriate versus read tools, and flags that approval will be requested. However, it names no alternative and gives no conditions such as when to restart a container versus starting or recreating one.

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

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

With no annotations, the description carries the full burden and does disclose two non-obvious traits: the operation is read-only and it is a terminating one-shot snapshot rather than a streaming tail. It does not mention permissions, host prerequisites, or the shape of the returned metrics, so it is helpful but not exhaustive.

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

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

A single line that front-loads the resource and behaviour with zero filler; the parenthetical is dense but every clause (one-shot, read-only, --no-stream analogy) earns its place.

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

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

For a one-parameter, read-only stats tool with full schema coverage and no output schema, the definition supplies enough to call it correctly. A brief note on what metrics or format come back would make it fully self-sufficient, but little 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% and the single optional 'host' parameter is fully documented in the schema, including the HOMELAB_HOSTS convention and the local-machine default. The description adds nothing about parameters, so baseline 3 applies.

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

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

States a specific verb+resource: reads one-shot CPU/memory usage for Docker containers, with the analogy 'docker stats --no-stream' pinning the exact semantics. It is clearly separable from siblings like docker_ps and docker_logs by resource, though it does not name 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?

'One-shot' and '--no-stream' imply this is for a single snapshot rather than continuous monitoring, which is useful context. However, no when-to-use guidance, prerequisites, or explicit sibling routing (e.g. use docker_ps to enumerate containers) is given.

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

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

With no annotations, the description carries the full burden and does disclose the important traits: it is a WRITE action, the client will prompt for approval, and old_text must occur exactly once. It omits what happens on failure (zero or multiple matches), whether edits are atomic/reversible, and any permission or path-allowlist constraints beyond the schema's note.

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

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

Three short sentences with zero filler, and the operation plus its uniqueness constraint are front-loaded. Every sentence earns its place.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essentials: what it does, that it is a guarded write, and the single-match precondition. Failure behavior and reversibility are the only meaningful gaps remaining.

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, including the 'must occur exactly once' constraint that the description repeats. The description adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Replace text in a file'), which is unambiguous and clearly distinct from siblings like read_file or docker_logs. It does not explicitly name an alternative tool, but the purpose itself is sharp enough that no confusion arises.

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

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

There is no guidance on when to choose this over alternatives such as run_command (e.g. sed) or a hypothetical write_file, nor any stated prerequisites like needing a unique anchor. Usage is only implied by the description of the operation.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key safety trait ('read-only'), which is real value, but says nothing about recursion depth, hidden files, output format, error behavior, or permission requirements.

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

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

A single front-loaded sentence with zero waste. It is efficient, though its extreme brevity leans toward under-specification rather than exemplary structure.

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

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

For a simple read-only listing tool with full schema coverage and no output schema, the essentials are present. However, nothing tells the agent whether the listing is recursive, how results are returned, or how path-scope violations are surfaced.

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

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

Schema description coverage is 100%, so the schema already documents both 'host' (HOMELAB_HOSTS name, omitted for local) and 'path' (absolute path inside HOMELAB_PROJECT_DIRS). The description adds no syntax or constraint 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+resource ('List directory contents'), which is immediately distinguishable from file-content siblings like read_file and host-list siblings like list_hosts. It does not, however, explicitly name any sibling or scope boundary, so an agent gets no routing help beyond the obvious noun.

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, when-not-to-use, or alternative guidance. The parenthetical '(read-only)' hints at safety but not at when this tool should be chosen over read_file, run_command, or list_hosts.

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

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

With no annotations, the description carries the full burden, and it does add one genuinely useful trait: the list is static configuration from an environment variable, not live network discovery. However, it says nothing about ordering, whether the env var being unset yields an empty list or an error, or what authentication/connectivity is implied.

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, resource, and data source all appear before any trailing detail, and every clause earns its place.

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

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

For a trivial zero-parameter read tool with no output schema, the description covers what is returned (the configured servers) and where it comes from. The only meaningful gap is behavior when HOMELAB_HOSTS is unset or malformed, which an agent would need to know to handle the empty-result case.

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

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

The tool takes zero parameters, which is the baseline-4 case per the rubric; the description correctly signals that no filtering or arguments are accepted. There is nothing further for it to document here.

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

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

States a specific verb ('List') and resource ('remote servers'), plus the exact configuration source (HOMELAB_HOSTS env var), so the agent knows precisely what is enumerated. It does not explicitly distinguish itself from siblings like system_info or service_status, which also read host-level state, but the resource is narrow enough to be unambiguous.

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

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

Usage is implied rather than stated: an agent can infer this is the discovery step before targeting a specific host, but there is no explicit when-to-use, when-not-to-use, or named alternative among the siblings. No prerequisites or failure conditions 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?

Mentions 'read-only' (though no annotations exist) and the local vs remote behavior from param description. Does not disclose required permissions, output format, or executable requirements.

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 concise sentence with no waste, front-loading the core purpose and read-only nature.

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?

Simple tool with one optional param, but lacks details on output format (process names, PIDs) and behavioral traits like error handling or permissions. Annotations absent, so description should carry more burden.

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 parameter is fully documented in the schema. The description adds no extra meaning about the 'host' parameter beyond what's in the schema.

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

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

States a specific verb (List) and resource (listening TCP ports and owning processes), and the analogy 'ss -tlnp' makes the exact operation unambiguous.

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

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

Implied usage via 'like ss -tlnp' but no explicit when/when-not or alternatives. Does not differentiate from siblings like service_status or system_info.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses only that the operation is read-only and that output is paginated by lines; it omits what happens with missing paths, permission failures, non-text/binary files, or how the host parameter affects execution.

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

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

A single tight phrase with the core action and safety profile front-loaded — no wasted words. It is arguably under-specified rather than verbose, which is a completeness concern rather than a conciseness one.

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 four-parameter read tool with full schema coverage and no output schema, the description covers the essentials: action, pagination, and non-mutating nature. It leaves gaps around file-type expectations, encoding, and error behavior, but nothing an agent strictly needs to construct a valid call is absent.

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

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

Schema description coverage is 100%, so the schema already documents host, path, limit, and offset including defaults and bounds. The description adds only the pagination concept, which the schema's limit/offset descriptions already convey, 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 ('Read a text file') plus a scope qualifier (line pagination), which cleanly separates it from siblings like edit_file and list_dir. It does not explicitly name the sibling it contrasts with, but the read-only framing makes differentiation easy.

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 '(read-only)' tag implies this is the non-mutating counterpart to edit_file, but there is no explicit when-to-use statement, no conditions or prerequisites, and no routing to alternatives such as list_dir for directory enumeration. Nothing tells the agent when to prefer this over other read paths.

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

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

With no annotations, the description carries the full burden and does well: it flags this as an EXECUTION action, warns that the MCP client will prompt for approval, and pins the security boundary to HOMELAB_ALLOW_COMMANDS. It stops short of describing return contents (stdout/stderr/exit code) or failure behavior.

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

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

Three short sentences, front-loaded with purpose, then the safety/approval note, then the constraints. Every clause carries information; nothing is redundant or buried.

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

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

For a mutating execution tool with no output schema, the description covers approval, allowlisting, and single-command limits, which is what an agent most needs before invoking. Minor gap: no hint about how results (exit code, stdout/stderr) are surfaced to the caller.

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

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

Schema description coverage is 100%, so all four parameters (host, command, workdir, timeout_secs) are already documented, which sets the baseline at 3. The description reinforces the 'single command' nature of `command` and the project-directory constraint on `workdir`, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Run a dev command') with concrete examples (tests, build, typecheck, git) and scope ('inside a project directory'). It clearly reads as an execution tool, distinct from read_file/edit_file siblings, though it never names an alternative tool 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?

Gives clear operating context and hard constraints: an approval prompt will fire before execution, only a single command is allowed, and the binary must be present in HOMELAB_ALLOW_COMMANDS. It does not, however, compare against alternatives such as docker_* or db_query tools for related tasks.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the read-only nature of the operation, which is the key behavioral fact for a status check, but says nothing about what status data is returned, how failures for unknown services behave, or remote-execution implications.

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

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

A single short sentence with the resource front-loaded and the read-only qualifier trailing it. No filler, nothing to trim.

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

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

For a two-parameter read-only probe with no output schema, the definition is minimally adequate. Because there is no output schema, the description could have sketched what status fields come back or noted that a non-running service still returns successfully, but it leaves that to inference.

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

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

Schema coverage is 100%, so both 'host' and 'service' are fully documented in the schema, including the HOMELAB_HOSTS reference and local-machine default. The description adds nothing beyond the parameter level, which matches the baseline when the schema does the heavy lifting.

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

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

States a specific verb (Check) and resource (systemd service status), which is enough to separate it from docker_* and file-based siblings. It stops short of naming when it should be preferred over any alternative, so it is clear but not sibling-differentiated.

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

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

There is no guidance on when to use this versus system_info, docker_ps, or run_command for service inspection. The '(read-only)' tag implies a safe inspection use case but gives no explicit conditions or exclusions.

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

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

With no annotations, the description carries the full behavioral burden; it does declare read-only, which is real value. However it omits remote-execution concerns such as what happens if the named host is unreachable or whether the call blocks, leaving meaningful gaps.

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

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

One tight sentence, front-loaded with the verb and resource, that enumerates the returned metrics without filler. Every clause earns its place.

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

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

For a one-optional-param read-only tool with no output schema, listing the metric set is enough to call it correctly; the schema handles host semantics. Missing only failure-mode context for an unreachable remote host.

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 'host' parameter already documents HOMELAB_HOSTS names and the omit-for-local behavior. The description mentions nothing about the parameter, so it earns only the 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?

The description gives a specific verb (Get) plus the exact resource and the four metrics returned (uptime, load average, memory, disk usage). It doesn't explicitly distinguish itself from close siblings like disk_detail or service_status, which would be needed for a 5.

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

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

There is no statement of when to use this tool rather than disk_detail (deeper disk info) or service_status (per-service state), even though disk usage overlaps directly with a sibling. The parenthetical '(read-only)' hints at safety but not at selection.

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