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

With no annotations present, the description carries the burden and does disclose meaningful behavior: a confirm gate is required, context must be in an allowed host folder or an https git URL, and build args leak into image history. It omits whether the build blocks/streams, timeout behavior, and whether an existing tag is overwritten.

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 action and the confirm requirement, then documents the two required parameters in compact sentences. The security warning is a worthwhile addition; nothing is redundant, though the formatting is slightly fragmented.

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

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

Output schema exists so return values need not be described, but for a 10-parameter mutation tool with zero annotations, missing explanation of target (multi-stage builds), platform, and no_cache leaves meaningful invocation ambiguity. The safety-critical parts are covered; the optional-flag semantics are not.

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 0% across 10 parameters, and the description explains only context (formats, constraints), tag (image name example), dockerfile (path inside context), and build_args (secret-leak warning). Optional parameters host, pull, target, no_cache, and platform remain completely undocumented in both schema and 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?

States a specific verb and resource — 'Build an image with docker build' — which is unambiguous and clearly distinct from siblings like docker_pull_image or docker_run, but it never explicitly contrasts itself with those siblings.

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

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

Provides a hard prerequisite ('Needs confirm=true') and restricts context to an allowed folder or https git URL, which is real usage guidance, but gives no when-to-use/when-not guidance relative to docker_create, docker_run, or docker_pull_image.

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 largely does so: it declares which commands execute immediately, that anything else shows a preview first (a built-in safety gate), and that background=true returns a job checked via server_job. It does not explain what confirm does in relation to that preview, nor what as_root escalates.

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 purpose sentence, then examples, the read-vs-write rule, and the background hint — each sentence adds information. Slightly ragged line breaks but 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?

An output schema exists so return values needn't be explained, and the execution-safety story is well covered. However, for a catch-all tool that can do anything from listing images to running privileged containers, the missing semantics for confirm, as_root and host leave real gaps an agent could get wrong.

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 0% across five parameters, so the description must compensate. It clarifies args as the text after 'docker' with good examples and explains background=true, but leaves host, as_root and confirm undefined — three of five parameters, including a privilege-escalation flag.

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 arbitrary docker commands — and immediately scopes it as the fallback 'for things the other docker tools do not cover', which cleanly separates it from the many docker_* siblings like docker_ps, docker_build and docker_run.

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

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

Gives an explicit exclusion rule (anything the other docker tools already cover) plus concrete examples and the background/server_job workflow. It does not name which specific sibling to prefer for common tasks, so the agent must scan the sibling list itself.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the confirm=true requirement, but does not explain destructive effects, permissions, idempotency, or what happens to a running container during stop/restart.

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

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

The description is a single front-loaded sentence with no wasted words. It immediately states the available actions and the confirmation prerequisite.

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 container tool with no annotations and 0% schema coverage, the description is too thin. The output schema covers return values, but the description still omits host/container semantics, safety implications, and sibling differentiation.

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 0%, so the description must compensate. It implies the allowed action values and mentions confirm=true, but says nothing about the required container parameter or the optional host parameter, leaving half the parameters undocumented.

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 specific lifecycle verbs (start, stop, restart, pause, unpause) and the resource (one container), so the agent can identify the operation. It does not explicitly differentiate from siblings like docker_stack_action or docker_run/create, but 'one container' provides useful 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 only usage guidance is the prerequisite 'Needs confirm=true'. There is no explanation of when to choose this tool over alternatives such as docker_stack_action, docker_run, or docker_remove, nor any when-not-to-use conditions.

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

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

With no annotations, the description carries the safety burden and does it well: it discloses that destination files are overwritten, that confirm=true is required, and that host_path is sandboxed to an allowed folder. It stops short of saying what happens on missing source paths or error conditions, and return shape is covered by the output 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?

The core operation and the confirm requirement are front-loaded in the first two clauses, followed by tightly packed semantics for direction, path constraints, and flags. No sentence is filler.

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

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

For a destructive, 7-parameter tool with no annotations, the description covers the critical risks (overwrite, confirmation, path sandboxing) and the ambiguous parameters. Error behavior and the meaning of 'host' are the only remaining gaps, and the output schema covers return values.

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 0%, so the description must compensate, and it explains the non-obvious parameters: direction with explicit source->destination arrow mapping, host_path's allowed-folder restriction, keep_owner's '-a' behavior, and confirm. Only 'host' and 'container' remain unexplained, and those are largely self-evident.

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 ('Copy files between a container and the Docker host') and grounds it in the familiar 'docker cp' primitive. It is immediately distinguishable from the host-only siblings like server_file_move or server_file_write.

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 conditions: use when moving files across the container/host boundary, and notes the confirm=true prerequisite and allowed-folder constraint. It does not explicitly route the agent to the host-file siblings when no container is involved, so usage is clear but without stated 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 usefully discloses the confirm=true requirement and the two creation modes, but it does not discuss permissions, failure behavior, idempotency, or what happens if the named resource already exists.

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

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

The description is front-loaded with the core action and confirm requirement, then gives compact kind-specific parameter guidance. The formatting is slightly uneven, but most content is useful and not repetitive.

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

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

For an 11-parameter mutation tool with no annotations, the description covers the critical network/volume distinction and most creation parameters. The presence of an output schema reduces the need to explain return values, though the missing host/name details and lack of failure semantics leave some gaps.

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

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

Schema description coverage is 0%, so the description must compensate, and it does explain many important parameters: kind, driver, subnet, gateway, ip_range, parent, internal, and options with an NFS example. It still leaves host and name largely unexplained, and confirm is only partially covered.

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: create a network or volume, and it explicitly splits behavior by kind. An agent can distinguish this from sibling tools like docker_run, docker_networks, and docker_volumes 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?

It gives clear context for use by requiring confirm=true and explaining that kind must be network or volume. It also explains kind-specific fields, but it does not explicitly name alternatives such as listing existing networks/volumes or removing them.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'Show' weakly implies a read, but it never confirms the operation is non-destructive, never says whether it contacts the daemon or may be slow on large hosts, and never addresses the `host` targeting behavior. With zero annotation coverage this is a meaningful gap for even a simple query tool.

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

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

One sentence, front-loaded with the verb, enumerating the four resource categories with no filler. Nothing is padded or redundant.

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

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

The presence of an output schema means return shape need not be explained. However, with no annotations and an undocumented `host` parameter, the definition leaves an agent guessing about read-only safety and remote-host targeting, so it is only adequate rather than complete.

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

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

The single `host` parameter has 0% schema description coverage and a bare empty-string default, and the description says nothing about it — an agent cannot tell whether it is a daemon address, a context name, or a label, nor what blank means (local daemon?). With only one parameter, this is the one place the description should have compensated.

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 ('Show') and the exact resource breakdown — images, containers, volumes, build cache — which maps clearly to a `docker system df`-style aggregate report. It is distinguishable from docker_images or docker_volumes because it reports space consumed across all four categories rather than listing one resource type, though it never says so 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?

There is no when-to-use guidance, no mention of the natural pairing with the docker_prune sibling (check usage before reclaiming), and no statement of prerequisites such as Docker daemon availability. The agent must infer the workflow entirely.

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 load and does well: it discloses that the tool is destructive ('the command can do anything inside the container'), documents the two-phase preview/confirm gate, and explains that no shell is used by default so pipes and redirects fail unless shell=true. It omits failure behavior, timeouts, and output truncation, but the output schema covers 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?

Front-loaded with the core action, then one fact per line covering destructiveness, the confirm workflow, and shell semantics. Dense and largely waste-free; the mid-sentence line breaks ('but no shell is used / (no pipes)') slightly fragment the reading flow.

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

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

For an arbitrary-command execution tool with an output schema present, the description covers the safety protocol and execution semantics well enough to call it correctly. The unaddressed 'host' parameter and absent error/timeout behavior are the remaining gaps.

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

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

Schema coverage is 0%, so the description must compensate for seven undocumented parameters. It usefully explains shell, workdir, user, confirm, and how command is tokenized, but 'host' is never mentioned at all and 'container' is only implied by the first sentence — a meaningful gap given zero schema descriptions.

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

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

States a specific verb and resource: 'Run one command inside a running container', which implicitly separates it from docker_run/docker_create (new containers) and docker_cli. The parenthetical '(no terminal, no input)' sharpens the scope. It never names a sibling explicitly, so the differentiation is inferred 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?

Gives a concrete workflow: a preview is shown first, then call again with confirm=true after the user approves — this is exactly the sequencing an agent needs. It does not say when to prefer this over docker_cli or docker_run, so alternatives are left implicit.

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

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

No annotations are provided, so the description carries the full burden; "List" implies read-only but that is never stated. It says nothing about which daemon is queried (local vs. the host parameter), what happens if the host is unreachable, or whether output is paginated, leaving the key behavioral questions unanswered.

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 line with no filler, well matched to a trivial list operation. It stops short of being under-specified to the point of being unhelpful structurally, though it leaves gaps elsewhere.

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

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

An output schema exists, so the description needn't explain return values, and a one-line summary is defensible for a simple listing. However, with no annotations and an undocumented host parameter, the definition leaves the agent without enough to invoke it confidently against a remote daemon.

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 single host parameter has 0% schema description coverage and the description never mentions it, so the agent cannot tell whether it targets a remote Docker daemon or defaults to local. The listed fields (name, tag, size, age) describe the response, not the input, so they add no parameter meaning.

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?

"List images" states a specific verb and resource, and the enumerated fields (name, tag, size, age) confirm it is an inventory read, distinguishing it from siblings like docker_ps and docker_volumes. It does not explicitly call out those siblings, but the resource noun does the disambiguation work.

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?

Nothing says when to use this versus docker_ps, docker_disk_usage, or docker_inspect, nor any precondition such as needing a running daemon or a reachable host. The agent must infer usage entirely from the tool name.

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

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

With no annotations, the description carries the full burden, and it does add real value: secret environment variable values are redacted, and volume inspection surfaces driver and options such as the NFS address. It omits other behavioral facts an agent needs, such as whether this is strictly read-only, what happens for a missing name, and how the `host` parameter changes 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 the verb and resource scope, and each sentence adds something (scope, volume-specific output, redaction). The dangling '(kind)' reference in the first sentence is awkwardly placed and slightly interrupts the opening.

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

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

An output schema exists, so return values needn't be described, and the redaction note covers a key safety concern. However, for a 3-parameter tool with zero schema description coverage and no annotations, the unexplained `host` parameter leaves a meaningful hole an agent cannot resolve from structured fields.

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 0%, so the description must compensate. It does clarify `kind` by listing the accepted values (container, volume, network, image), which the schema leaves as an unconstrained string, but `host` is never explained and `name` semantics are only implied.

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 (Show details) and enumerates the four resource types it covers, with the `kind` parameter naming the selector. The singular-resource scope implicitly separates it from list siblings like docker_ps and docker_images, but 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 description never says when to use this versus docker_ps, docker_volumes, docker_networks, or docker_images, nor does it establish the typical list-then-inspect workflow. Usage is only inferable from the word 'details'.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses that password/token-looking values are redacted in output, which is real behavioral context an agent would otherwise not know. However it says nothing about whether the container must be running, whether the call is read-only/safe, or whether output is a snapshot vs stream, which matters for a zero-annotation tool.

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

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

Two short sentences with the action front-loaded and no filler. The trailing redaction note is separated by a stray blank line but is still brief and earns its place.

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

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

An output schema exists, so return values need not be explained. What remains missing is meaningful for a 4-param, unannotated tool: the semantics of `host`, whether tail defaults to 100 lines, and any prerequisite that the container exist or be running.

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 0%, so the description must compensate for all four parameters. It explains the `since` format well ('10m, 2h, or 2026-10-11') and 'last lines' hints at `tail`, but `host` (default empty string) is entirely unexplained — an agent cannot tell what a host means here or whether it may be omitted.

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 the last lines of a container's log.' An agent immediately understands it is a read of container logs. It does not differentiate from the sibling docker_stack_logs, which is a plausible confusion point, so it stops short of a 5.

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

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

There is no when-to-use / when-not-to-use guidance and no mention of alternatives such as docker_stack_logs (stack-level) or docker_inspect. The 'since like 10m, 2h...' sentence documents a parameter format, not usage selection, so the agent must infer the routing itself.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only listing but never states safety, host scoping, or whether remote hosts are supported; the single 'host' parameter goes entirely unexplained.

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 line with zero filler. It is efficient, though the terseness borders on under-specification given the undocumented parameter.

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

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

An output schema exists so return values need not be described, and for a simple list operation the core is covered. However, the unexplained 'host' parameter and absence of any scoping or safety context leave a meaningful 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 0% and the description mentions no parameters at all; it only enumerates output fields. The 'host' argument's meaning (local vs remote daemon) is left entirely to inference.

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 (networks) and names the three fields returned. An agent can distinguish it from docker_volumes/docker_images, though the description never explicitly contrasts with 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?

No guidance on when to call this versus alternatives like docker_inspect or docker_disk_usage, and no mention of the host parameter's role in selecting a target.

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 discloses the critical behaviors: it is destructive, it shows a preview first, and it requires a two-step confirmation. It does not elaborate on irreversibility or exactly what the preview contains, but for a prune tool these disclosures cover the main risks.

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

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

The description is front-loaded with purpose, followed by a compact enumeration of 'what' values and the confirmation workflow. Every sentence and fragment earns its place; there is no redundancy or 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?

Given that an output schema exists, the description need not explain return values, and it adequately covers the destructive nature and required confirmation. The only gap is the undocumented 'host' parameter, but the core usage for a prune operation 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 0%, so the description must compensate. It thoroughly defines the 'what' parameter by listing each accepted value with clarifications (e.g., 'containers (stopped)', 'volumes (not used by any container)') and explains the 'confirm' workflow. However, the 'host' parameter is never mentioned, leaving one of three parameters undocumented.

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

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

The description states a clear action ('Clean up unused things') and enumerates the resource types affected (containers, images, networks, volumes, builder), making the tool's scope specific. It distinguishes itself from targeted siblings like docker_remove by being a bulk prune operation, though the opening phrase is slightly generic before the enumeration.

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

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

It gives explicit procedural guidance: 'Shows a preview first. Run again with confirm=true after the user says yes.' This tells the agent exactly how to sequence the call and when to seek confirmation. It does not name sibling alternatives such as docker_remove for selective cleanup, but the destructive workflow is clearly scoped.

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

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

With no annotations, the description carries the full burden. It does helpfully disclose the returned fields and that the default (all=true) already includes stopped containers, which is a non-obvious behavior. It says nothing about permissions, host scoping, or ordering/pagination of 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?

Three short lines, front-loaded with purpose and returned fields, followed by the two filtering behaviors. No filler; every sentence adds 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?

An output schema exists, so return values needn't be described in depth, and the description is adequate for a simple read-only listing. The undocumented 'host' parameter and absence of any note on scope or default host selection leave a meaningful hole.

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 0%, so description must compensate. It explains two of three params meaningfully — notably clarifying that all=true is the default and includes stopped containers — but the 'host' parameter is completely undocumented in both schema and description, a real gap for a Docker tool that may target remote hosts.

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

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

The description opens with a specific verb and resource ("List containers") and enumerates the fields returned, which clearly separates it from docker_images, docker_networks, and docker_volumes. It never explicitly names those siblings, so the differentiation is implied 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?

Guidance is limited to parameter behavior (all=true includes stopped containers, name_contains filters by name) rather than when to pick this over docker_inspect or docker_stats. The intended use case of listing/overview is only implied by the verb 'List'.

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

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

With no annotations, the description must carry the behavioral load. It does add one genuinely useful, non-obvious fact: the call requires confirm=true, which signals a gated mutation rather than a plain read. It says nothing about registry authentication, overwrite behavior for existing tags, or failure modes, so the remaining burden is unmet.

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 action and an inline example, with no filler. Every clause carries information; the brevity is the right shape, the gaps are coverage rather than verbosity.

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

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

An output schema exists so return values need not be explained, but for a 3-parameter mutation with no annotations and 0% schema description coverage, the definition leaves 'host' entirely undefined and omits cautionary context (auth, existing-image handling). It is not complete enough for confident invocation.

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

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

Schema coverage is 0%, so the description must compensate, and it only partially does: 'image' gets a format example and 'confirm' is flagged as effectively required. The 'host' parameter — the most ambiguous one, plausibly selecting which Docker host/server the pull targets — is not mentioned at all.

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 ('Download an image') with a concrete format example (ghcr.io/example/app:latest), which clearly separates it from listing siblings like docker_images or building tools like docker_build. It does not explicitly name an alternative, so it stops short of a 5.

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

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

The only guidance is the prerequisite 'Needs confirm=true'; there is no statement of when to pull versus alternatives (docker_build, docker_tag_image, docker_run), nor what happens if the image already exists locally, nor any registry/auth precondition.

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

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

With no annotations, the description carries the full burden and does so: it declares destructiveness, the two-step preview/confirm flow, the running-container refusal, that volume removal deletes data, and the NFS nuance where only the setting is stored. These are exactly the risk facts an agent needs before mutating state.

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?

Every sentence adds a distinct operational constraint and the destructive warning is front-loaded. The arbitrary line wrapping splits sentences awkwardly, but no content 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 destructive 4-parameter tool with no annotations, the description supplies the safety workflow, preconditions, and data-loss caveats, and an output schema exists so return values needn't be described. The unmentioned 'host' parameter is the only meaningful 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 0% and the schema provides only bare titles, so the description must compensate. It does: 'kind' is bounded to the four enumerable resource types, 'confirm' is tied to the post-user-approval step, and 'name' is implied as the target object. Only 'host' goes unmentioned, a minor gap.

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

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

The description opens with a concrete verb and enumerates the exact resource kinds ('Delete one container, image, volume or network'), and the word 'one' implicitly separates it from the bulk sibling docker_prune. An agent can identify the tool from the first line alone.

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 an explicit execution sequence ('Shows a preview first. Run again with confirm=true after the user says yes') and a precondition ('A running container is not removed. Stop it first'), which points the agent at docker_container_action. It stops short of naming sibling alternatives outright, so not a 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?

With no annotations, the description carries the full burden and does well: it discloses detached/background execution, the confirm gate, the allowed-folder constraint for host volumes, and prohibited capabilities (privileged mode, devices, docker socket). It does not mention image-pull behavior or what happens on name collisions, but the output schema covers returns.

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 and confirm requirement, then follows with the compose alternative, parameter syntax, and hard restrictions. Every clause adds information; nothing is redundant.

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

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

For a 12-parameter mutation tool with zero annotation coverage, the description covers execution mode, safety gate, volume restrictions, and an alternative tool, which is substantial. However, half the parameters (host, network, restart, user, workdir, env, command, name) remain unexplained in either schema or description.

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 0% across 12 parameters, so the description must compensate. It gives concrete syntax for the trickiest parameters (ports like '8080:80', volumes like 'myvol:/data') and explains confirm, but leaves env, host, name, user, command, network, restart, and workdir completely undocumented.

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: 'Start a new container in the background (docker run -d).' It distinguishes itself from docker_stack_write as the ephemeral alternative, but does not differentiate from sibling docker_create or docker_cli, which also create 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?

Explicitly names the alternative ('For anything that should stay, a compose stack (docker_stack_write) is better') and states the mandatory confirm=true requirement. It lacks guidance on when to use docker_create or docker_cli instead.

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

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

With no annotations, the description must carry the full behavioral burden. It usefully discloses that destructive actions exist and what down vs down_volumes removes, but the final sentence is truncated ('are destructive and also '), leaving the confirm requirement for the destructive actions unstated, and it says nothing about host targeting or permissions.

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

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

The structure is good: a one-line purpose followed by the action catalogue and then the confirm/destructive caveats. But the text ends mid-sentence, which is waste in the opposite direction – the definition is incomplete rather than merely tight.

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

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

An output schema exists, so return values need not be explained, and the action catalogue covers the core of the call. Still missing: which destructive actions require confirm (sentence truncated), what host means for stack selection, and the result of a build or recreate beyond the shell-equivalent note.

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 0% and action has no enum, so the description is the only place the valid action values and their semantics are defined – substantial value beyond the schema. However, the stack and host parameters are never explained, so it does not fully compensate for the coverage gap.

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

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

The description names the verb and resource ('Run a Compose action on one stack') and then enumerates the exact operations, so an agent can distinguish it from siblings like docker_stack_status, docker_stack_write, or docker_stack_file. The only weakness is the generic framing verb 'run' before the enumeration does the real work.

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 defines each allowed action value and its effect (up vs pull vs update vs recreate), which is essentially the when-to-use guidance for this tool. It also flags which actions require confirm=true and which are destructive. It does not route the agent to any alternative sibling when a non-stack operation is needed.

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

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

With no annotations, the description carries the full burden, and it discloses the most important trait: secret values are hidden in the output, so agents won't expect credentials. It implies a read-only inspection but says nothing about permission requirements or what happens when the stack doesn't 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?

Three short sentences, each earning its place: what it does, why to use it, and the secret-hiding caveat. Front-loaded and free of 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?

An output schema exists, so return formatting needn't be explained, and the core behavior plus the secret-masking caveat are covered. The unexplained 'host' parameter is a real gap for a tool that is otherwise simple.

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 0% for two parameters. The description only indirectly conveys that "stack" identifies the stack; the "host" parameter is never mentioned, so an agent has no idea it can target a remote host or what the default means.

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: it resolves a stack's compose file with variables interpolated, which is meaningfully different from docker_stack_file (raw file) and docker_stack_status. It stops just short of naming the sibling that would make the distinction 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?

"Good for finding a missing or wrong value in the .env file" gives a clear, concrete use case, so an agent knows to reach for it when debugging interpolation problems. It does not name an alternative or state when not to use it.

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

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

With no annotations, the description carries the full behavioral burden. It valuably discloses that secret values are hidden and the .env file is never shown, but it does not state read-only semantics explicitly, error behavior for missing stacks, or any host-related caveats.

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

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

Three short sentences, front-loaded with the action and followed by the two most important behavioral caveats. 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?

An output schema exists, so return-value explanation is not needed, and the redaction behavior is covered. However, the host parameter is entirely unexplained and there is no context on stack naming or error conditions, leaving a meaningful gap for a two-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It mentions 'stack' only implicitly and gives no meaning for the 'host' parameter or its default empty value.

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 the compose file of a stack'), clearly identifying the operation. It does not explicitly distinguish itself from sibling tools like docker_stack_config or docker_stack_write, so an agent must infer the difference from names.

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 verb 'Show' and the resource, but there is no explicit guidance on when to use this versus docker_stack_config, server_file_read, or docker_stack_write. No prerequisites or alternative routing are given.

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

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

With no annotations, the description carries the full burden; 'Show' implies a read-only operation, which is helpful. However, it does not disclose default tail behavior, how 'host' targets a remote daemon, or any rate/size limits on the returned log volume.

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 action, that earn their place by covering scope and time format. Minor grammatical awkwardness ('since like 10m') but 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?

An output schema exists, so return values need not be explained. For a 5-parameter tool with zero schema descriptions, the missing meaning of 'tail' and 'host' leaves gaps an agent must guess at.

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 0% across 5 parameters, so the description must compensate. It only clarifies the 'since' format with examples ('10m, 2h, 2026-10-22') and the stack-vs-service relationship; 'tail' (default 100) and 'host' remain completely undocumented.

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 the last log lines') and clarifies the scope choice between a whole stack and one service. It implicitly distinguishes itself from the sibling docker_logs (container-level) but never names that sibling 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 'a whole stack, or one service of it' implies when the service parameter matters, but there is no explicit guidance on choosing this over docker_logs or docker_stack_status, and no prerequisites or exclusions are stated.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only listing but never says so, and it omits whether results span all hosts or a single one, how errors are surfaced, or what 'running' derives from.

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 compact sentence with no waste, and the core resource is front-loaded. It is under-specified rather than verbose, so brevity is not the problem here.

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

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

An output schema exists, so return values need not be explained. However, with no annotations and an undocumented host parameter, the description leaves meaningful gaps for correct invocation.

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

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

The single 'host' parameter has 0% schema description coverage and a default of empty string, and the description never mentions it. An agent cannot tell whether omitting it means all hosts, the local host, or an error.

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 (Compose stacks) plus the additional signal of running state and the on-disk folder convention. It is reasonably distinguishable from docker_stack_status, though it never explicitly contrasts itself with that 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?

No guidance on when to use this versus docker_stack_status or docker_stack_config, and no mention of what 'host' means or when to supply it. The agent must infer everything from the tool name.

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

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

No annotations are provided, so the description carries the full burden. The verb 'Show' implies a read operation, but the description does not state that it is read-only, whether it requires host permissions, or any other behavioral traits beyond the obvious.

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. Its brevity is appropriate for a simple status lookup 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?

An output schema exists, so return values need not be described. However, the lack of annotations and the undocumented 'host' parameter leave meaningful gaps for an agent trying to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'stack' refers to a single required stack, but it does not explain the optional 'host' parameter at all.

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: it shows the containers of one stack and their state. An agent can distinguish this from stack listing or individual container listing, though no sibling is explicitly named.

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

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

The description gives no guidance on when to use this tool versus alternatives such as docker_ps, docker_stacks, or docker_inspect. Usage is only implied by the tool name and the phrase 'one stack'.

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

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

With no annotations, the description carries the full burden and does well: it discloses the confirm=true gate, the write target path, the validation step (`docker compose config`), and rollback semantics ('the old file is put back (or the new file removed)'), plus that it is not a start operation. It stops short of stating permission/auth requirements or multi-host 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?

Front-loaded with the action and the confirm requirement, then the mechanics, then the alternative tools. No filler sentences, though the file-path sentence and the variable guidance make it slightly dense for what is essentially a write-with-validate operation.

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 a 0%-coverage schema, the description covers atomicity, rollback, validation, and the not-a-start caveat; an output schema exists so return values needn't be explained. The unexplained `host` parameter is the main remaining hole.

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 0%, so the description must compensate. It explains `confirm` ('Needs confirm=true'), implies `stack` via the target path, and implies `content` is the compose file body, but the `host` parameter is never mentioned at all — a real gap given four undocumented parameters.

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

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

States a specific verb and resource: 'Create a new stack, or replace the compose file of one, then check it.' That precisely separates it from docker_stack_file (read), docker_stack_config (validate only), and docker_stack_action (start/stop), and it names the follow-up sibling 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 explicit routing: 'Nothing is started: use docker_stack_action up' after writing, and 'write that with server_file_write' for .env secrets. Both alternatives and the condition that selects them are named, leaving little to inference.

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

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

With no annotations, the description carries the burden: 'Show' and 'running containers' imply a non-destructive read limited to active containers, which is useful. However it says nothing about whether the call blocks or how long sampling takes, whether a Docker daemon/host connection must be configured, or multi-host 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?

One sentence, front-loaded with the verb and resource, with the temporal constraint at the end. 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?

An output schema exists, so return values need no explanation, and for a simple live-stats tool the description covers the essentials. The remaining gap is the undocumented host parameter and lack of any note on sampling behavior.

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 0% for the single 'host' parameter, and the description never mentions it or explains that it selects which Docker host to query. The param is simple enough that a baseline 3 is defensible, but the description does not compensate for the coverage gap.

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 ('Show') plus resource ('CPU, memory and network use of running containers') and scope qualifier ('right now'). It is clearly distinguishable from docker_ps (container listing) and docker_logs, though it never names a sibling 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 'right now' implies a live snapshot as opposed to historical metrics, but there is no statement of when to prefer this over docker_ps, docker_inspect, or docker_disk_usage, and no 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?

With no annotations, the description must carry the behavioral burden, and it does disclose one important trait: a confirmation gate ('Needs confirm=true'). It does not state that tagging is additive/non-destructive, whether the source image must already exist locally, or what happens on name collision.

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 zero filler; the core action comes first and the confirmation requirement follows. The parenthetical adds CLI mapping value rather than repeating the name.

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

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

An output schema exists, so return values needn't be explained, and the confirm gate is covered. However, an undocumented 4-parameter schema with no annotations leaves the agent guessing about source/target/host semantics and failure conditions.

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 0% across 4 parameters, and the description only clarifies `confirm`. The mapping of 'an image' and 'a second name' to the `source`/`target` params is left implicit, and `host` is not mentioned at all.

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 ('Give an image a second name') and anchors it to the familiar CLI operation via '(docker tag)'. It is clearly distinguishable from siblings like docker_pull_image or docker_remove, though it names no explicit alternative.

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

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

The prerequisite 'Needs confirm=true' is stated, which tells the agent the call requires an explicit confirmation flag despite the schema default of false. There is no guidance on when to tag versus when to build/pull/copy, so usage context is only implied.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. 'List' implies a read-only, non-destructive operation, but the description says nothing about permissions, whether the host is local or remote, or behavior when no daemon is reachable.

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

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

It is a single front-loaded fragment with zero waste, but it is terse to the point of under-specification rather than efficient completeness. The returned-fields clause is the only substantive content.

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

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

An output schema exists, so return values needn't be described, and for a simple list tool the bar is low. Still, the undocumented 'host' parameter and the absence of annotations leave a real gap an agent would want closed before invoking it.

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

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

Schema description coverage is 0% and the sole parameter 'host' (defaulting to empty string) is never mentioned in the description. The agent gets no indication of what 'host' selects or what an empty value means, so the description fails to compensate for the coverage gap.

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 volumes') and even names the returned fields (name, driver), which is enough to distinguish it from docker_images and docker_networks. It doesn't explicitly call out sibling relationships, but the resource noun does the differentiating work.

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 or when-not-to-use guidance and no mention of alternatives (e.g., docker_inspect for volume detail or docker_prune for removal). The agent must infer from the name alone that this is a read-only enumeration.

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, and it discloses that this is destructive, that a preview is returned first, that confirmation is user-gated, and that recursive deletes an entire tree. It leaves out permission requirements (what as_root changes), error behavior on non-empty folders without recursive, and whether deletes are recoverable.

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 critical warning and the preview-then-confirm flow are front-loaded, which is good. However, "Destructive." appears twice and "Never forced." is a fragment whose meaning is ambiguous, so the text is short but not tight.

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

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

An output schema exists, so return values needn't be described, and the safety workflow is well covered. For a destructive, zero-annotation tool with 0% param coverage, though, missing host targeting and as_root privilege implications leave an agent unable to predict failures or scope correctly.

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

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

Schema description coverage is 0%, so the description must explain 5 parameters. It meaningfully clarifies two of the least obvious ones (confirm, recursive) and implicitly path, but host and as_root are never mentioned, leaving their scoping and privilege semantics undocumented anywhere.

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?

It names a specific verb and resource ("Delete a file or an empty folder") and scopes it to the Docker host, which separates it from container-level siblings like docker_remove. It doesn't explicitly contrast with server_file_move or server_file_write, so sibling differentiation is implied 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?

It gives a concrete two-step workflow: call once for a preview, then re-run with confirm=true after the user agrees. It lacks explicit exclusions (e.g., when to prefer docker_remove for containers or non-Docker-host filesystems), but the sequencing guidance is unusually clear.

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

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

With no annotations, the description carries the burden and does disclose several non-obvious behaviors: confirm=true is mandatory, old_string must be exact and unique unless replace_all is set, and lines containing hidden secrets are unmatchable. It omits that backup defaults to true and that as_root can escalate privileges, so the mutation risk profile is only partially covered.

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

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

Three short, front-loaded sentences with no filler; the confirm requirement and the matching constraints each earn their place. Breaking the constraints onto their own line aids scanning.

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

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

For a mutating 8-parameter tool with no annotations, the definition covers the core matching contract but leaves the side-effect surface thin: backup behavior, as_root privilege escalation and host targeting are never mentioned. An output schema exists, so return-value explanation is correctly omitted.

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 0% across 8 parameters, so the description must compensate; it explains old_string, new_string, replace_all and confirm semantics well, but says nothing about backup, as_root, or host. Four of eight parameters remain undocumented anywhere.

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 ('Change part of a text file: replace old_string with new_string'), which clearly distinguishes it from the sibling server_file_write (whole-file overwrite) and server_file_read. An agent can select it without opening the schema.

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

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

Implicitly scoped to partial edits and constrained to files the agent can read, plus a hidden-secrets caveat, but it never names server_file_write as the alternative or says when a full rewrite is preferable. 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?

With no annotations present, the description carries the full burden and does disclose two meaningful traits: SERVER_MCP_FILE_ROOTS may restrict visible folders, and as_root=true escalates via sudo. It does not state whether the operation is read-only/safe by default, what happens on permission errors, or how large directories behave, leaving notable gaps for an unannotated tool.

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

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

Front-loaded with the core purpose and return shape, followed by short constraint sentences that each add information. The phrasing 'as_root=true uses sudo' is slightly terse, but nothing is redundant.

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

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

An output schema exists, so return values needn't be described, and the description covers the listing scope, sandbox limits, and three of four parameters. The unexplained 'host' parameter and the absence of any usage-vs-sibling guidance are the only omissions.

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 0%, so the description must compensate, and it does for three of four parameters: path (empty = stacks folder, no leading slash = relative to it), depth (1 to 4 levels), and as_root (uses sudo). Only 'host' is left completely unexplained, which is the one clear hole.

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

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

Opens with a specific verb and resource ('List files and folders on the Docker host') and enumerates the returned columns (type, mode, owner, size, date, path). An agent can immediately distinguish this read-only listing from siblings like server_file_read, server_file_write, or docker_copy.

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 supplies default behavior (empty path = stacks folder, relative path resolves there) and the root sandbox constraint, which is genuinely useful. However, it never says when to prefer this over server_file_read or docker_stack_file, nor any preconditions or exclusions; usage must be inferred 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?

With no annotations at all, the description carries the full burden. It does disclose two real behaviors: parent directories are created recursively, and the call is gated behind confirm=true, which signals a mutating operation. It says nothing about idempotency (what happens if the folder already exists), error behavior, or what permissions are needed, leaving substantial gaps for an unannotated mutation tool.

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

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

Two short sentences, zero filler, with the action and scope stated before the confirmation requirement. Nothing is padded and nothing repetitive.

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

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

An output schema exists, so return values need no explanation, but the tool is a mutation on a remote host with zero annotation coverage and zero schema descriptions. An agent still cannot tell whether the call is idempotent, whether it fails on an existing folder, or what 'as_root' and 'host' change about execution — the description should have filled at least some of that.

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 0% across four parameters, so the description must compensate. It covers only 'confirm' (explicitly required true), while 'path', 'host', and especially 'as_root' — a privilege-escalation flag with real consequences — are entirely unexplained. The 'on the Docker host' phrasing hints at host targeting but never clarifies what the host parameter accepts.

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 ('Make') and resource ('a folder') plus the scope ('on the Docker host') and the recursive behavior (missing parent folders created). This clearly separates it from the file-oriented siblings like server_file_write or server_file_list, which operate on files rather than directories.

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 supplies one concrete precondition — 'Needs confirm=true' — which is genuinely actionable. However, it offers no when-to-use framing or exclusions, e.g. whether server_file_write already creates parents, or when to prefer this over writing a file at that path. Usage is implied, not 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?

With no annotations at all, the description carries the full burden, and it does disclose the meaningful safety behavior: a confirmation gate and non-overwriting default when the destination exists. It omits whether the move crosses hosts/filesystems, what privileges are required, and whether as_root or host selection changes 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, no filler, and the gating requirement (confirm=true) is stated before the optional override behavior. Every sentence carries information an agent needs before calling.

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

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

An output schema exists, so return values need not be explained, and the two risk-relevant flags are covered. However, for a 6-parameter call with zero schema descriptions and no annotations, the undocumented host and as_root parameters and the absence of any permission or path-format context leave real gaps.

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

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

Schema description coverage is 0% and there are 6 parameters, so the description must compensate. It explains only confirm and overwrite; source, destination, host, and as_root are left entirely to bare titles, with no path format, host-scope, or privilege guidance.

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

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

The description opens with a specific verb pair and resource ('Move or rename a file or folder') and scopes it to the Docker host, which is enough to separate it from server_file_write, server_file_edit, or server_file_delete. It doesn't name any sibling explicitly, so it stops short of a 5.

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

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

It states a hard prerequisite ('Needs confirm=true') and gives a clear conditional rule for when to set overwrite=true versus leaving an existing destination untouched. It never says when to choose a different tool (e.g. server_file_write to replace content), so it lacks the explicit alternatives that a 5 requires.

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

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

With no annotations, the description carries the burden and discloses important behavior: secret-bearing files are never shown, secret values are hidden, and large files are truncated by a named environment variable. It still omits permission requirements and what as_root changes, but the safety and truncation context is substantive.

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 short and front-loaded: action first, then security restrictions, then size limits. Every sentence adds operational value without unnecessary preamble.

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

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

An output schema exists, so return values need not be explained, and the description covers secret hiding and truncation. However, for a tool with three undocumented parameters and no annotations, it is not complete enough about path, host, and especially as_root behavior.

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 0%, so the description must compensate for all three parameters. It only loosely implies path and host via 'text file on the Docker host' and says nothing about as_root, leaving key invocation semantics undocumented.

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: reading a text file on the Docker host. That is clearly distinguishable from sibling tools such as server_file_write, server_file_edit, and server_file_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?

Usage is implied by 'Read a text file' and the sibling set makes the read-vs-write distinction obvious, but the description does not explicitly say when to choose this tool over server_file_list or how host/as_root affect selection.

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

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

With no annotations, the description does real work: it discloses that whole-file replacement overwrites content, that backup produces <name>.bak, that make_dirs creates missing folders, and that an existing file keeps its mode and owner. It omits anything about privilege requirements (as_root is never explained) or failure behavior, 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?

Front-loaded with the core action and the confirm requirement, then parameter semantics packed tightly. Every sentence carries information; only the slightly fragmented line-per-parameter layout costs it the top mark.

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

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

An output schema exists, so return values needn't be explained, and the overwrite/backup/mode/encoding semantics are all present for a nine-parameter destructive write. The unexplained host and as_root parameters, plus no mention of what happens on permission failure, are the remaining gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does — mode ('optional octal mode such as 644 or 755'), encoding ('text, or base64 for binary files'), make_dirs, backup, and confirm all get meaning beyond their bare names. Two of nine parameters, host and as_root, receive no explanation at all.

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 ('Create a file, or replace a whole file, on the Docker host') and immediately distinguishes the overwrite case from the incremental-edit case. An agent can tell this apart from server_file_edit without opening either schema.

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

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

Explicitly routes the agent: 'For a small change to an existing file use server_file_edit instead', and states the confirm=true requirement up front. Both the when-to-use and when-not-to-use conditions are named.

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

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

With no annotations, the description carries the full burden. It does disclose a real behavioral trait beyond the name: it actively probes connectivity to every host, which implies latency and possible per-host failures. It says nothing about timeouts, what happens to unreachable hosts, or whether the call is read-only/side-effect free.

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, leading with the primary action (list hosts) and appending the secondary behavior (connection test). Nothing to trim and nothing structurally misplaced.

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 tool with an output schema, the description covers the essential action and the extra connection-test behavior. The main residual gap is operational: no hint that the call may be slow or that results are per-host, which matters for an agent sequencing this before other Docker calls.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the scope is the full configured host set rather than a caller-supplied subset.

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 the Docker hosts") plus a secondary action ("test the connection to each"), which separates it from container-level siblings like docker_ps and from server_info. The phrase "this tool knows" is slightly vague about where hosts come from (configured host list), but the operation is unmistakable.

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

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

Usage is only implied: an agent can infer this is the discovery/health-check step for hosts, but the description never says when to prefer it over server_info, docker_ps, or server_service, nor any prerequisites (e.g., that hosts must be preconfigured). No exclusions or alternatives are stated.

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

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

With no annotations provided, the description carries the burden, and it does disclose the important trait that the operation is read-only and enumerates the categories of system data exposed. However, it does not explain the meaning or effect of the host parameter, whether remote hosts are supported, or any permission/auth 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?

The description is extremely concise and front-loaded: one sentence enumerates the returned data, followed by a two-word safety note. 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?

An output schema exists, so return-value details need not be in the description, and the listed data categories give a good sense of scope. However, the undocumented 'host' parameter is a meaningful gap for correct invocation, and there is no usage guidance relative to sibling 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 0%, and the single 'host' parameter has no description in the schema. The tool description never mentions the host parameter at all, so an agent cannot infer whether it targets the local server or a remote one.

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 clear verb and resource ('Show the system') and enumerates the specific system data returned: OS, kernel, uptime, CPU, memory, disks, and network. It is more specific than a bare title, but it does not explicitly differentiate itself from siblings such as server_processes or docker_disk_usage.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The only contextual hint is 'Read only,' which describes safety rather than usage selection.

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

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

With no annotations, the description carries the full burden and does disclose the key behaviors: five action modes, the read-only vs. mutating split, the preview-then-confirm pattern for cancel/clean, and that clean removes finished-job records. Gaps remain around what cancel does to a still-running process and any 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?

Purpose is front-loaded in one short sentence, followed by a compact enumerable action list and then the operating rules. Every sentence carries information; nothing is padded. The colon-list format is dense and scannable.

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?

Six params with zero schema descriptions and no annotations, but an output schema exists so return values need no explanation. The description covers most of what an agent needs to invoke correctly, with the unexplained host parameter the main omission.

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 0%, so the description must supply all parameter meaning. It enumerates the action values, explains as_root's semantics (jobs started as root), implies lines via 'last lines of the log', and implies confirm via the preview behavior. The host parameter is entirely unexplained, leaving one of six params undocumented.

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 resource (background jobs) plus origin ('started with background=true'), and an enumerated action set makes the tool's scope immediately legible. It implicitly distinguishes itself from server_run, which starts these jobs, though it never names a sibling. Clear, but sibling differentiation rests on inference.

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 says which actions are non-destructive and immediate ('list, status and output run right away') versus which need confirmation ('cancel and clean show a preview first'), and gives a hard prerequisite ('jobs started as root must be read with as_root=true'). It does not point at any alternative tool for job-related tasks, so 4 rather than 5.

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

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

With no annotations, the description must carry the full behavioral burden; it does declare 'Read only', which is the key safety signal. However, it silently leaves out that `as_root` elevates privileges and that `host` retargets the call to a remote machine — both material behaviors for an agent to know 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 short sentences, front-loaded with purpose and followed by the parameter shorthand and the safety note. No wasted words; every clause adds 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?

An output schema exists, so return values need no explanation, which lowers the bar. Still, for a six-parameter tool with zero schema descriptions, omitting `host` and `as_root` (a privilege flag) leaves a meaningful gap in what an agent needs 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?

Schema description coverage is 0%, so all meaning comes from the description, yet it only explains four of six parameters (unit, lines, since, grep) and gives the useful example format '1 hour ago'. The two remaining parameters, `host` and `as_root`, are undocumented anywhere, so compensation is incomplete.

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 ('Read the system log') and anchors it to the underlying tool (journalctl), so an agent immediately knows what it does. It does not explicitly contrast with docker_logs, the obvious sibling for container logs, leaving that distinction to be inferred.

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 host-logging purpose implies when to use it, but there is no explicit guidance on choosing between server_journal and docker_logs, nor any prerequisites or exclusions. Usage must be inferred from the purpose statement alone.

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

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

With no annotations, the description carries the full burden and does well: it discloses that update/install/remove/upgrade show a preview first, that background mode returns a job id immediately, and where to poll that job. The notable gap is that it never explains what `confirm` does or what happens on the second call after a preview, which is central to a destructive operation's safety model.

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 purpose, then action semantics, then the background-job caveat — a sensible ordering for an agent skimming. Nearly every clause earns its place; the only slack is that the action list is compressed into a run-on sentence rather than clearly separated.

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

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

An output schema exists, so return values needn't be described, and the background/job-id workflow is covered. For a mutating package-management tool with zero annotations, however, the unexplained `confirm` flow and absent mention of privilege requirements leave a real safety 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 0%, so the description must compensate. It defines `packages` as a space separated list and explains `background` (returns a job id immediately) thoroughly, but leaves `host` and — more importantly — `confirm` completely undescribed, even though `confirm` is the gate between preview and actual package mutation.

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 ('Manage system packages') plus the concrete package managers it auto-detects, and enumerates the actions (list_updates, search, update, install, remove, upgrade). Nothing in the sibling list overlaps with package management, so an agent can route here unambiguously.

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

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

Gives explicit selection guidance inside the tool: which actions are read-only, which are preview-then-apply, and when to set background=true ('Use it for upgrade and install, which can take minutes'), with a pointer to server_job for checking. It does not state when to prefer this over adjacent tools like server_run or server_service, so it stops short of 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?

With no annotations, the description carries the full burden and does add real value: it warns that a preview is always shown first and that the SSH link will drop during execution, which prevents an agent from misreading a disconnection as failure. It does not state that the operation is destructive/irreversible, what permissions are required, or how the preview relates to the confirm flag.

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, front-loaded sentences with no filler; the action semantics and the connection-drop warning both land early. The 'Always shows a preview first' sentence is terse to the point of ambiguity about whether a follow-up call is needed.

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

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

An output schema exists, so return values need no explanation, and the description covers the key hazard (SSH drop) and the preview behavior. Still, for a destructive host-level mutation with zero annotations and zero schema coverage, it should clarify the preview/confirm workflow and the meaning of '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 coverage is 0%, so the description must compensate; it does clarify the required 'action' parameter by enumerating 'reboot or poweroff'. However, 'host' (empty default, presumably local) and 'confirm' are never explained, and the preview sentence does not explicitly tie to confirm, leaving two of three parameters undocumented.

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 ('Reboot or power off the host') plus the allowed action values, which pins down exactly what the tool does at the host level. It does not explicitly name why it differs from siblings like docker_container_action or server_service, but 'host' scoping makes the distinction inferable.

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 tool's trigger conditions are only implied: use it when you need a host reboot or poweroff, with the action values enumerated. There is no guidance on when not to use it, whether a container/service restart would be a safer alternative, or prerequisites such as confirm.

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 usefully discloses that the operation is read-only and that sorting is supported, but it omits whether host targeting is required, how limits behave, or any permission considerations.

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

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

The description is very short, front-loaded with the core action, and contains no filler. The telegraphic fragments ('sort: cpu or mem') are efficient, though slightly cryptic compared with a fully structured sentence.

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

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

The tool is simple and an output schema exists, so return values need not be described. However, for a 3-parameter tool with 0% schema coverage and no annotations, the description leaves critical invocation details—especially host targeting and limit semantics—unexplained.

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 0%, so the description must compensate. It explains only the 'sort' parameter (cpu or mem); the 'host' and 'limit' parameters are left entirely undocumented, including the meaning of host's empty default and limit's default of 15.

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 ('Show the busiest processes'), making the core action immediately clear. It does not name a sibling alternative, but no direct process-listing sibling exists among the Docker-oriented tools, so the purpose remains distinguishable.

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 'sort: cpu or mem' fragment gives a usage hint for one parameter, and 'Read only' signals safe usage. However, it never states when to choose this tool over alternatives or what context (e.g., local vs remote host) makes it appropriate.

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

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

No annotations exist, so the description carries the full burden and does: it discloses the preview/destructive marking model, that root commands always preview first, that privileged operations require as_root with sudo, that credential files (.env, keys) are blocked, and that background runs return a job id immediately. These are exactly the behavioral traits an agent cannot infer from the schema.

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

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

Long but front-loaded: the host-vs-container distinction is sentence one, and every subsequent sentence adds a distinct rule rather than restating the schema. It could be tightened slightly by grouping the safety-tier sentences, but there is little filler.

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

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

An output schema exists, so return values need not be described, and the one return behavior that matters (background returns a job id) is called out. For a six-parameter, high-risk execution tool, the description covers permissions, confirmation, blocking rules, and async behavior.

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 0%, so the description must compensate and mostly does: as_root, confirm, background, and command are all given semantics beyond their titles. However, the 'host' parameter and the 'timeout' parameter are never explained, leaving two of six parameters undocumented in both schema and prose.

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 one shell command') plus a precise scope boundary ('on the Docker host itself, not inside a container') that separates it from docker_exec and docker_cli. The starting directory is also given, so the agent knows exactly what is being invoked.

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 sorts commands into auto-approved read-only sets and ones requiring confirm=true, and names server_job for checking background jobs plus server_file_read/write/edit as preferred alternatives for file work. The 'when to use background' rule (>~40s) is stated rather than left to inference.

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

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

With no annotations, the description usefully discloses that status is read-only and immediate while mutation actions show a preview first. It does not explain how the preview is confirmed/executed, what permissions or root behavior apply, or which actions can disrupt the service.

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

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

The description is three short sentences, front-loads the core purpose and actions, and includes only behaviorally relevant details. There is no wasted wording.

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

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

An output schema exists, so return values need not be described. The preview workflow is a helpful addition, but for a five-parameter mutation-capable tool with no annotations and 0% schema coverage, more parameter and permission context is needed.

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 0% for five parameters, so the description must compensate. It clarifies the action values and the status-vs-preview behavior, but leaves host, unit, as_root, and confirm undocumented.

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: managing a systemd service, and enumerates the supported actions. It is clearly distinct from Docker and file-management siblings, but it does not explicitly differentiate itself from adjacent server tools such as server_processes or server_power.

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 action list and the note that status runs immediately while other actions preview first imply the intended workflow. However, there is no explicit guidance on when to prefer this tool over alternatives or when not to use it.

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