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

Annotations cover the safety profile (non-readonly, open-world, non-idempotent), so the bar is lower, and the description adds genuine context: network/disk consumption, a required human confirmation, and output truncation behavior ('its end when long'). It stops short of stating permissions or failure/reversibility semantics, but adds real value beyond the annotations.

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

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

Three short sentences, front-loaded with the core action before the behavioral caveats. Every sentence carries information, though the parenthetical about truncation is slightly tucked away rather than prominent.

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

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

With an output schema present, return values are already covered, and the description adds the operational constraints an agent most needs (network/disk use, human confirmation). It is nearly complete, missing only build-arg and cache-handling nuance for the two undocumented parameters.

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 60%, with tag, context, and dockerfile documented in the schema while noCache and buildArgs are undescribed. The description only loosely restates context/dockerfile ('local folder with a Dockerfile') without syntax or defaults, so it does not compensate for the 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 (build), resource (image), source (local folder with a Dockerfile), and an additional effect (tag it). This clearly distinguishes it from registry-oriented siblings like pull_image and tag_image; an agent can pick 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?

It gives a caution ('Uses the network and disk: confirm with the person first'), which implies a precondition, but never states when to use build_image versus pull_image or run_container, nor any exclusions. Usage is implied rather than explicitly framed.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it explicitly says it never installs anything and instead tells the person what to do, which prevents a likely misconception about automatic remediation.

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

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

The description is two efficient sentences. The first sentence front-loads what is checked and what is returned; the second adds the critical non-mutating behavior without any 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?

With no input parameters, an output schema present, and annotations covering read-only and closed-world behavior, the description supplies everything an agent needs: the purpose, the reported information, and the guarantee that no installation occurs.

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 no parameters, so the baseline for parameter semantics is 4. There is no parameter information to add or omit, and the schema coverage is 100%.

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 ('Check') and resource ('the programs this server needs installed') and states exactly what will be reported: presence, version, and installation guidance. It is clearly distinct from the container and lab management siblings, which do not inspect host prerequisites.

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

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

The description explains what the tool does but gives no explicit guidance on when to call it versus alternatives, nor any prerequisites or exclusions. Usage must be inferred from its purpose 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?

Goes well past the annotations: discloses network and disk consumption, that long output is truncated to its end, that failures explain themselves at the end, and that the agent should confirm with the person first. These are the exact operational facts annotations cannot convey, and they are consistent with openWorldHint=true and destructiveHint=false.

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

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

Front-loaded with the action and its boundary, and every following clause carries information (use cases, return shape, failure behavior, side effects, confirmation). The opening sentence is dense with nested clauses and the parenthetical '(its end when long)' is slightly cryptic, but there is no filler.

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

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

With an output schema present and 100% schema coverage, the description only needs to cover intent, boundaries, and side effects — and it does all three, including the human-confirmation requirement for a mutating, network-touching operation. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds a real semantic: only services that declare a build are built, and 'all, or some' clarifies the services parameter's default scope beyond the schema's 'all with a build when missing'. The file, pull, and noCache parameters are left entirely to the schema.

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

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

States a specific verb and resource ('Build the images of a Compose project's services') plus an explicit scope limiter ('that have a build') and boundary ('without starting anything'). This cleanly separates it from compose_up and from the single-image build_image sibling without opening any schema.

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

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

Gives concrete use cases ('to check a Dockerfile change, or to have the images ready') and the negative condition 'without starting anything', which implicitly routes starting to compose_up. It does not name the alternative sibling or state prerequisites beyond the human-confirmation instruction, so it falls just short of 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?

Beyond annotations that already mark this as destructive and idempotent, the description discloses exactly what is removed, that volumes entail data deletion, that the server asks for person confirmation naming what goes, and that refusal results in no action. This is rich behavioral context for a destructive operation.

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

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

The description is front-loaded with the core action, then details the volume and confirmation behavior. It is compact, with no filler, and every clause adds operational meaning.

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 annotations declare destructiveness and idempotency and an output schema exists, the description supplies everything an agent needs: scope, volume data impact, confirmation requirements, and no-op behavior on refusal.

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

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

The schema covers folder and file adequately, but the volumes boolean has no schema description. The description compensates by explaining that volumes removes volumes and their data and triggers a server-side confirmation, adding meaning beyond the bare boolean.

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: stop and remove a Compose project's containers and networks, optionally its volumes and data. This clearly distinguishes it from sibling tools that operate on individual containers, images, networks, or compose_up.

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 usage context for a destructive operation by instructing the agent to confirm with the person first, and it explains the server-side confirmation flow when volumes are included. It does not explicitly name alternatives such as remove_container or prune, but the scope is clear enough to route correctly.

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

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

Annotations already disclose readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is partly covered. The description adds meaningful context beyond them: the command can mutate the service and requires user confirmation. It does not mention the 60s default timeout or rate/output limits, keeping 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?

Three tight sentences with the core action front-loaded and no filler. Slightly dense but every clause earns its place.

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

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

An output schema exists, so return values ('exit code and output') need no elaboration, and annotations carry the safety profile. The confirmation caveat and command-format guidance round it out, though the undocumented timeout and project-file parameters leave minor 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 40%, so the description must help. It clarifies the 'command' parameter well (array form, shell-line workaround ['sh','-c','…']), but leaves 'file', 'folder' and 'timeoutSeconds' entirely to the sparse schema, so the compensation is partial.

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

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

States a specific verb and resource ('Run a command in a running service of a Compose project') plus the return value (exit code and output). It implies a Compose-service scope distinct from container-level exec, but never names the sibling exec_in_container, so an agent must infer the differentiation.

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

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

Provides a conditional safety rule ('confirm with the person first unless it only reads'), which is useful when-to guidance. It does not state when to prefer this over exec_in_container or lab_exec, so the alternative-selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the useful default of 200 lines per service and the per-service fan-out behavior, but says nothing about truncation limits, whether stopped services are included, or whether output is interleaved/ordered.

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

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

One sentence, zero filler, with the resource and the default behavior front-loaded. Nothing could be removed without losing meaning.

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-shape explanation is not required, and the safety profile comes from annotations. Still, for a 4-parameter tool at 50% schema coverage, the description leaves the tail and service parameters under-explained and omits prerequisites such as the project needing to be up.

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

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

Schema description coverage is only 50%: folder and file are documented in the schema, while tail and service carry no description there. The description partially compensates by stating the 200-per-service default and hinting at single-service selection, but never explains what tail does or that it caps at 5000, nor gives service-name syntax.

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

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

States a specific resource ('a Compose project's services') and scope ('or one' service), and implies retrieval of the last N log lines. It is distinguishable from container_logs at a glance because it is project-scoped rather than container-scoped, though it never names that sibling to sharpen the distinction.

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

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

No when-to-use, when-not-to-use, or alternative is given. An agent cannot tell from this text whether to prefer compose_logs over container_logs or lab_logs for a given situation; the only hints are implicit in the resource wording.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds only the vague word 'state' and says nothing about scope (single project), pagination, or what happens when the project isn't running — minimal added behavioral value.

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 short sentence with no wasted words, but it is a sentence fragment that never states an action. Brevity here reads as under-specification rather than disciplined conciseness.

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 annotations cover the read-only nature. However, for a project-scoped query tool the description never establishes the action or the project-scoping behavior, leaving the definition only minimally viable.

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

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

Schema description coverage is 100% and both parameters are self-describing ('folder' as absolute path to compose.yaml, 'file' for a non-default compose file). The description contributes nothing about parameters, so the baseline 3 applies.

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

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

The description is a noun phrase rather than a verb+resource statement, but it does name the specific resource (a Compose project's services) and what is reported (their containers' state). It is distinguishable from siblings like compose_logs or list_containers, though the agent must infer that this is a read/list operation.

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 indication of when to use this versus list_containers, inspect_container, compose_logs, or compose_up. There are no prerequisites, no exclusions, and no mention of the required 'folder' context that selects the project.

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?

Adds substantial context beyond the annotations: it runs whatever the compose file says, including privileged services and host mounts, builds what has a build, and runs in the background. The security/privilege warning is exactly the behavioral disclosure an agent needs and the annotations do not provide.

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

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

Front-loaded with the action in the first clause; the second sentence is slightly run-on but every part (privileged services, host mounts, confirm-first) earns its place as safety guidance.

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 description covers action, behavior, and the safety precondition. It is nearly complete for a tool that executes arbitrary compose files, though it could say more about its relationship to compose_down.

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

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

With 50% schema coverage, the description compensates by explaining build behavior ('building what has a build'), the partial-service option ('or only some'), and the compose-file relationship ('its compose file'). It adds meaning over the bare schema but does not fully pin down each parameter.

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

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

States a specific verb ('Start') and resource ('a Compose project's services') with scope qualifiers ('in the background', 'or only some'). This cleanly distinguishes it from siblings like start_container (single container), compose_down, and compose_ps.

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 strong usage directive: read the compose file first and confirm with the person, naming anything dangerous. This is a clear caution protocol but does not name alternative tools or explicit when-not-to-use conditions beyond the danger caveat.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing return behavior: logs are the last lines by default (200), truncated from the start when very long, and include both stdout and stderr. This is genuinely useful context for a read tool, though it omits error/absent-container behavior.

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

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

A single sentence that front-loads the resource and scope and packs default and truncation behavior without waste. Every clause earns its place.

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

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

An output schema exists, so return-value details need not be re-explained, and the description covers the key behavioral fact (truncation of long logs). It is complete enough for a read-only log tool, missing only the sibling differentiation and failure-mode notes.

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

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

Schema description coverage is 100%, so the schema already documents container, tail, and since. The description only restates the default tail (200) and the truncation implication, adding little beyond the structured fields. Baseline 3 applies.

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

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

The description names a specific resource (a container's log lines) and streams (stdout and stderr), so the agent immediately knows this reads logs. It does not, however, differentiate itself from the sibling log tools (compose_logs, lab_logs), which an agent must distinguish between.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives like compose_logs or lab_logs. Usage is only weakly implied by the resource being 'a container's' logs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the runtime-state requirement, which is the main failure mode. It does not mention what happens on a stopped container beyond implying failure.

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: the first front-loads what is returned and its Docker analogue, the second states the precondition. No wasted text.

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

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

With a full output schema, one well-documented parameter and annotations covering safety, the description only needed to add the precondition — which it does. It could go one step further by disambiguating from container_stats/container_logs.

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

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

Schema coverage is 100% and the single 'container' parameter is already documented as name-or-id with a pattern. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb+resource ('the processes running inside a container') and anchors it to a known primitive ('docker top'), plus enumerates the returned fields so the agent knows exactly what data comes back. That scope separates it from container_stats (resource usage), container_logs (stdout/stderr) and exec_in_container (new process).

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

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

'The container must be running' gives an explicit precondition for a successful call. It stops short of naming alternatives such as container_stats or container_logs for adjacent needs, so the agent must infer which sibling to pick.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. Beyond that, the description adds genuinely useful traits: it is a single snapshot rather than a stream, and stopped containers return zeros rather than erroring — both are behaviors 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?

Two dense sentences with the snapshot-vs-stream caveat and output fields front-loaded, then scope and use case, then the sibling pointer. No filler and nothing repeated from structured fields.

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

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

For a one-parameter, read-only tool with an output schema and annotations covering safety, the description covers scope, snapshot semantics, stopped-container behavior, and routing. Return-value structure is left to the output schema, which is appropriate.

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

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

Schema coverage is 100%, so the single 'containers' parameter is already documented. The description still adds meaning the schema does not: the default is all running containers, and naming a stopped container yields zeros rather than an omission or failure, clarifying the semantics of the filter.

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 resource and action — a live resource-usage snapshot for containers — and enumerates the metrics returned (CPU, memory, network, disk I/O, processes). It explicitly distinguishes itself from the sibling container_processes ('shows what runs inside one'), so an agent can separate the two without opening schemas.

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

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

It gives concrete use cases ('answer why the computer is slow or which container uses the most') and points to container_processes for a different need. It lacks explicit when-not guidance (e.g., historical trends or logs), so it stops short of full routing coverage.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=true, so the safety profile is covered. The description goes beyond that by naming exactly what is destroyed (pre-existing content at the local target) and prescribing a confirm-first step, though it says nothing about failure modes such as a missing source path.

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 core action front-loaded and the destructive caveat immediately after. Every sentence earns its place.

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

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

For a three-parameter copy tool with an output schema covering return values and annotations covering safety, the description supplies the one thing structured fields cannot: that the local destination is overwritten and confirmation is expected. It stops short of describing error behavior, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, so baseline is 3. The description only loosely maps 'from'/'to' to container file vs local path and adds no syntax, format, or edge-case detail beyond the schema.

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

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

States a specific verb (copy) and resource (a container's file or folder) plus the direction of transfer (to a local path), which cleanly distinguishes it from the sibling copy_to_container. An agent can pick between the two copy tools 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?

Gives a concrete operating condition: it overwrites the local destination, so the agent is told to confirm with the person first. It does not name alternatives or spell out the inverse tool explicitly, but the direction is unambiguous given the sibling set.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the concrete consequence — it overwrites whatever exists at the destination — plus a confirmation requirement before acting. That is real added value beyond the hint flags. It does not cover failure modes (e.g. whether the container must be running) or error 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?

Two sentences, zero filler, with the action stated first and the destructive warning immediately after. Nothing needs to be trimmed or moved.

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

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

With an output schema present, return-value explanation is unnecessary, and the annotations cover the safety profile. The description is nearly complete but omits operational prerequisites, such as whether the target container must be running or whether folders are copied recursively.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters ('from' as an absolute local path, 'to' as the container path, 'container' as a name or id). The description adds no format, syntax, or edge-case detail beyond it, so baseline 3 applies.

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

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

States a specific verb (copy) plus resource (local file or folder) and destination (a container's path), which cleanly separates it from the reverse-direction sibling copy_from_container. 'Into' makes the direction unambiguous without the agent needing to open 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?

The description gives a caution ('confirm with the person first') but no explicit when-to-use guidance or named alternatives, such as exec_in_container for in-place writes or copy_from_container for the reverse operation. Usage context is implied rather than stated.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description adds context annotations don't carry: the semantic meaning of internal (no outside reachability) and a human-confirmation requirement before execution.

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

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

Two short sentences, front-loaded with the action and followed by the key conditional and the confirmation caveat. No filler, though the terseness is partly why other dimensions have gaps.

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 complexity is low (2 params). Still, the description omits naming constraints, duplicate-name behavior, and any pointer to sibling network tools, leaving it minimally adequate.

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 the semantic intent of the 'internal' flag but says nothing about the 'name' pattern/constraints or the default of internal; partial compensation for two 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 network'), so an agent can distinguish it from create_volume or run_container by resource alone. It does not, however, explicitly contrast itself with siblings such as list_networks or remove_network, 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?

Gives one conditional hint ('internal if it shouldn't reach the outside') and one precondition ('Confirm with the person first'), which is genuine usage guidance. But it names no alternatives and no when-not-to-use case, leaving the agent to infer when create vs. inspect/list is appropriate.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety surface is covered. The description usefully adds the human-confirmation requirement, but says nothing about what happens on a name collision despite idempotentHint=false making that behavior non-obvious, and nothing about scope 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?

Two short sentences with no filler, and the primary action is front-loaded ahead of the caveat. Slightly terse for a creation tool, but nothing is redundant or padded.

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

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

Return values need not be described since an output schema exists, and the safety profile is fully covered by annotations, so the remaining burden is small. Nevertheless, collision behavior for a non-idempotent create and any scope/permission context are absent, leaving an agent to guess at failure modes.

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

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

Only one parameter, and schema description coverage is 0% — the pattern regex carries all the syntax constraints while the description contributes just the word "named", implying the string identifies the volume. That is a marginal addition over the schema, but the single-parameter baseline keeps it at the middle of the range rather than low.

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 named volume") plus the intent behind it (data persistence), which a reader can map onto the create/remove/list/inspect volume sibling cluster. The differentiator versus those siblings is only implied by the verb, not called out 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 a concrete when-to-use condition — "for data that outlives a container" — which separates it from ephemeral container storage, and adds a process prerequisite ("Confirm with the person first"). No when-not-to-use case or named alternative is offered, so it stops short of 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by scoping exactly which Docker resources are measured and noting the reclaimable-space angle, giving the agent a clear picture of what the read returns. No auth or rate-limit notes, but none are needed for a local read-only inspection.

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

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

A single front-loaded sentence that states the resource first and the scope second. Every clause earns its place with no filler.

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

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

For a zero-parameter, read-only reporting tool with an output schema already defining the return shape, the description supplies everything an agent needs: what is measured and how it relates to the prune action. Nothing essential is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The schema is empty with nothing to misinterpret, and the description correctly implies no arguments are needed to obtain the report.

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 resource (Docker disk usage) and enumerates exactly what is measured: images, containers, volumes, and build cache. It implicitly differentiates from the prune sibling by framing prune as the action that reclaims the reported space, though it never states outright that this tool only reports rather than reclaims.

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 mention of space that 'could be reclaimed by prune' implies the follow-up workflow, but there is no explicit when-to-use/when-not guidance or direct callout of the prune tool. Usage is 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered by structured data rather than prose. The description adds the useful framing that this is a non-destructive health probe, but no other behavioral traits (latency, whether it errors when the daemon is down, effect of a stopped engine) are disclosed.

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

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

Two sentences, front-loaded with the payload list and closing with the intended use case. The enumerated list is dense but every item is a distinct return field, so nothing reads as 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, and with zero parameters and read-only annotations the description carries little additional burden. The only real gap is not resolving the relationship to `server_info`.

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 no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool applies. No parameter semantics are missing.

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 enumerates exactly what information the tool returns: Docker version, engine OS/architecture, CPU and memory, and running/stopped container and image counts. That is far more specific than the title "Docker's information." It does not, however, differentiate itself from the sibling `server_info`, which a reader could reasonably confuse it with.

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

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

"A first call to check Docker is up" gives a clear usage context (health/connectivity check before other operations). It stops short of stating when not to use it or naming `server_info`/`check_requirements` as the alternative for related questions.

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?

Adds real context beyond the annotations: output is stdout and stderr combined, an exit code is returned, execution is terminated after timeoutSeconds, and the command can mutate the container. The mutation warning plus the confirmation requirement go beyond what destructiveHint=false conveys. It does not mention auth/permission requirements or how env/user/workdir affect execution.

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

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

Three tight sentences, front-loaded with purpose and return behavior, then the command-format detail, then the safety note. No filler. The middle sentence is somewhat dense but every clause carries information.

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

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

For a 6-parameter tool an output schema already covers return values, and the description covers the critical invocation semantics (argv format, timeout) and the mutation caveat. The remaining gap is the meaning/effect of env, user, and workdir, which an agent would have to infer.

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

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

Schema description coverage is only 17%, so the schema documents just the container parameter. The description compensates for the highest-value gap by explaining that command is an argv list, one argument per item, with the ["sh","-c","…"] idiom for shell lines, and it touches timeoutSeconds. env, user, and workdir remain undocumented in both places, so compensation is partial.

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

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

States a specific verb and resource: run a command in a *running* container, plus the return payload (exit code and combined stdout/stderr). This clearly separates it from create-and-run tooling like run_container. It does not, however, distinguish itself from the similar siblings compose_exec and lab_exec, so an agent must infer the scope difference.

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 concrete usage rule: confirm with the person first because the command can change the container, unless it only reads. That is actionable when-to-use guidance tied to side effects. It stops short of naming alternatives (compose_exec for compose services, lab_exec for labs) or stating exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered, but the description adds genuinely useful behavior beyond them: state includes an exit code, and env variables are returned as names only, never values, because they may hold secrets. That security-relevant caveat is exactly the kind of context annotations cannot carry. It does not say what happens when the container does not exist, leaving a small gap.

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

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

A single sentence, front-loaded with the resource, packing only meaningful field details plus one high-value parenthetical about secret env values. No filler, though the dense comma-list is slightly list-like rather than prose.

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

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

With an output schema present, describing return fields is not strictly required, yet the description is complete enough for an agent to know exactly what calling this returns and the read-only nature of the call. The only missing piece is failure behavior for an unknown container, which is minor for a read-only inspect tool.

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

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

Only one parameter, and the schema documents it at 100% coverage ('name or id, as its list gives it'). The description adds nothing about the parameter, so the baseline 3 for full schema coverage applies.

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

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

The description names the target resource ('a container') and enumerates exactly what information is retrieved (image, command, state, ports, mounts, networks, labels, env var names), which clearly separates it from siblings like inspect_image, inspect_network, and inspect_volume. The verb is only implied by the tool name ('inspect') rather than stated, so it falls just short of a fully self-contained statement of action.

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

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

There is no guidance on when to use this versus list_containers, container_logs, or any other sibling; the agent must infer that this is the deep-detail lookup. No prerequisites or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is fully covered. The description adds field-level context about what metadata is surfaced, but with an output schema present this largely restates the return shape rather than disclosing anything new (no auth needs, rate limits, or failure modes).

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

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

A single front-loaded fragment with zero filler; the field list is compact. It is efficient and well-structured, though as a colon-list fragment it lacks a framing clause that would state the intent more directly.

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

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

For a low-complexity, single-parameter, read-only inspection tool with a full output schema and safety annotations, the description is sufficient — the return values are covered by the schema. It adds little beyond structured data but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the single 'image' parameter (name or id) is already documented in the schema. The description adds nothing about parameter format or resolution beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (inspecting an image) and enumerates the fields returned (tags, size, architecture, command, entrypoint, ports, working directory, volumes, labels), which clearly distinguishes it from list_images. However, it never names or contrasts with the closely named inspect_container/inspect_network/inspect_volume siblings, so differentiation relies on the reader inferring the 'image' 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 description gives no when-to-use, when-not-to-use, prerequisite, or alternative guidance. There is no mention of when to choose inspect_image over list_images or the other inspect_* tools; the agent must infer all routing from the resource name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful scope detail that attached containers are included, but says nothing about error behavior for a missing network or any resolution rules beyond the schema's pattern.

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

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

A single compact sentence with no filler, and the most informative items are front-loaded. It is a sentence fragment rather than a full statement, which slightly weakens structure but wastes nothing.

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

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

With an output schema present, the description need not enumerate return values, and the annotations carry the safety profile, so the essentials are covered. The one gap is routing guidance versus list_networks/inspect_container, which matters in a 40+ sibling tool set.

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

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

Schema description coverage is 100% and the single 'network' parameter is already documented as 'name or id, as its list gives it'. The description adds no further syntax or format meaning, so the baseline 3 applies.

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

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

The description names the resource (a network) and enumerates the concrete details returned (driver, subnet, internal flag, attached containers), so an agent knows exactly what this retrieves. It lacks an explicit verb, relying on the title 'Inspect a network', and it does not distinguish itself from siblings like list_networks or inspect_container.

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 over list_networks (broad listing) or how it relates to inspect_container for the attached containers. The description is purely a content statement with no conditions, prerequisites, or alternatives 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the content preview (driver, mount point, labels, creation time), which is useful context, but says nothing about failure behavior for a missing volume or whether the volume must exist locally.

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

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

One short, front-loaded sentence with no filler. It is efficient, though it leans toward under-specification rather than tight phrasing.

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

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

An output schema exists, so the description need not enumerate return fields in depth, and annotations cover the read-only nature. With the single required parameter fully documented, an agent has enough to call this correctly; only the missing sibling contrast keeps it from being complete.

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

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

Schema description coverage is 100% and the single 'volume' parameter is documented in-schema as 'name or id, as its list gives it', so the structured field carries the load. The description adds no format, aliasing, or resolution detail beyond that, which is the expected baseline.

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

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

The description names the resource (a volume) and enumerates what the result contains: driver, mount point, labels, created time. Combined with the title 'Inspect a volume', an agent can distinguish it from list_volumes, create_volume, and remove_volume. However it is a bare noun phrase with no verb, and it never explicitly frames itself as the detail-lookup counterpart to list_volumes.

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 prerequisites, and no alternatives named. The agent must infer from the word 'details' that this is the single-volume drill-down after list_volumes, and nothing tells it whether a stopped/absent volume is acceptable input.

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

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

Annotations cover safety (destructiveHint=false, idempotentHint=true, openWorldHint=false), and the description adds genuinely new behavioral context: it executes inside the running lab, needs human confirmation first, and pass/fail is signaled by exit code with output explaining failures. It doesn't state what a failed run leaves behind, but the added context is substantial.

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 its success condition; the audience sentence and the confirmation warning each earn their place. Minor redundancy between the pass/fail explanation and the audience framing keeps it from a 5.

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

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

An output schema exists, so return values need not be explained, and the description correctly points to the output as the failure explanation. With one well-documented parameter and full annotation coverage, the definition is nearly complete; only the absence of alternative-routing guidance is a gap.

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

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

Schema coverage is 100% and the single 'lab' parameter is fully documented there, so the baseline is 3. The description only indirectly adds meaning by implying the lab must be running ('in its running service'); it adds no naming or format guidance beyond the schema.

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

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

States a specific verb and resource ('Run the lab's check (its lab.json) in its running service') and defines the success criterion (exit 0) plus the meaning of the output. This clearly separates it from siblings like lab_status or lab_logs, which observe rather than execute a check.

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

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

The description gives context for who it serves (teacher validating a statement/solution, student validating practice) and a caution ('confirm with the person first'), but it never says when to prefer this over lab_status, lab_exec, or check_requirements. Usage is implied rather than prescribed.

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

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

Goes well beyond the annotations by detailing exactly what is destroyed (containers, networks, volumes), what is lost (work inside them) versus what is retained (files in the lab folder), and adds a unique behavior: a server-side confirmation prompt that names what will be removed, with no action taken if declined.

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

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

Two sentences, front-loaded with the action and consequences, followed by the confirmation behavior. No wasted words and every part is useful.

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

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

Given the annotations (destructive, idempotent), the output schema, and the full schema coverage, the description covers everything needed: consequences, retained data, and the confirmation safety mechanism.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema; the description adds no extra meaning or formatting details beyond it, so baseline 3 applies.

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

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

States a specific verb and resource ('Stop a lab and remove its containers, networks and volumes'), and the scope is clear. However, it does not explicitly distinguish itself from sibling tools like lab_reset or compose_down, leaving the agent to infer the difference.

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 action described and the confirmation prompt, but there is no explicit guidance on when to use this tool versus alternatives such as lab_reset or individual container removal tools.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false but leave the agent with no sense of consequence; the description supplies that by warning the command "can change the lab" and requiring user confirmation for non-read commands. It also discloses the return shape (exit code and output). It does not cover timeout behavior, permissions, or side-effect scope, so it stops 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?

Three short sentences with no filler: what it does and returns, how to pass the command, and the caution. The caution and the critical usage rule are front-loaded rather than buried.

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

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

An output schema exists, so return-value detail is optional, yet the description still summarizes it; the mutation warning and command format cover the main risks of an exec tool. The only real omissions are timeoutSeconds semantics and any note on environment/working-directory context or failure modes.

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 50%: lab and service are documented in-schema, while command and timeoutSeconds are not. The description compensates well for command by specifying it is an argv list and showing the shell-line form, but says nothing about timeoutSeconds, leaving one of four parameters undocumented everywhere.

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 ("Run a command") and scopes it precisely to "one of a running lab's services," which separates it from the container-level siblings exec_in_container and compose_exec. It does not name those siblings explicitly, but the lab-scoped framing is enough for an agent to route correctly.

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

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

Gives concrete invocation guidance (command is a list; use ["sh", "-c", "…"] for a shell line) and a clear conditional rule for the risky case: confirm with the person first unless the command only reads. No exclusions or explicit alternative tool are named, but the when-to-be-careful guidance is unusually actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds the default retention (200 lines per service) and that it spans all services or a single one, but says nothing about ordering, aggregation across services, or truncation behavior.

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

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

A single front-loaded sentence with no filler, stating scope and default before any detail. The parenthetical "(or one)" is slightly elliptical but does not waste meaningful space.

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 annotations cover the safety profile. Still, for a log-reading tool the description omits ordering, multi-service aggregation, and any routing to the log siblings, leaving real 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?

Schema coverage is 67% — lab and service are documented, tail is not. The description supplies only the tail default (200), leaving the 1–5000 bound and per-service semantics of tail to the schema, so it adds modest value over the structured fields.

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

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

The description names a concrete resource (a lab's services' log lines) and a clear retrieval action, so an agent knows it returns logs rather than status or exec output. It does not, however, distinguish itself from the sibling log tools container_logs and compose_logs, so the resource scope (lab-level vs container/compose-level) must be inferred from the name.

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 prerequisites, and no named alternative. An agent must guess whether this is preferred over container_logs or compose_logs when both could return overlapping output.

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

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

The description adds substantial behavioral context beyond annotations: it names exactly what is destroyed (containers, networks, volumes), clarifies what persists (files in the lab folder), and describes the confirmation prompt and abort behavior. This goes well beyond the destructiveHint annotation.

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

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

Two sentences with zero waste, front-loading the reset concept and then detailing the consequences and confirmation flow. Every clause earns its place.

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

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

An output schema exists, so return values need not be described. The description covers destructive effects, persistence, and the confirmation workflow—everything an agent needs to call the tool correctly.

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

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

With one well-described parameter (100% schema coverage), the schema already explains that 'lab' is the lab's name from list_labs. The description does not add further detail about the parameter, so the baseline of 3 is appropriate.

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

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

The description specifies the exact operation (reset to a clean start) and what is removed (containers, networks, volumes) versus preserved (folder files). This clearly distinguishes it from siblings like lab_down or prune.

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 'back to a clean start' implies the use case for resetting state, and the confirmation step is described. However, it does not explicitly contrast against alternatives such as lab_down or explain 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The parenthetical '(empty when it isn't running)' adds a useful behavioral detail about output shape when the lab is down, but nothing about auth, cost, or error behavior is disclosed.

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

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

A single compact sentence with no filler, and the key scoping detail about empty output is front-loaded. It is efficient, though extremely terse.

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

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

With an output schema present, return values need not be described, and annotations cover the read-only nature. However, given six sibling lab_* tools, the description is incomplete on routing guidance, which is the main gap.

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

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

Schema description coverage is 100% and the single 'lab' parameter already carries its own description ('The lab's name, as list_labs gives it'). The tool description adds no additional meaning about the parameter, so the baseline of 3 applies.

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

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

The description names the resource ('a lab's services and their containers' state') but uses a noun phrase rather than a verb, so it describes what is returned more than what the tool does. Combined with the name lab_status the intent is inferable, but it does not differentiate from close siblings like lab_check or lab_logs.

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

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

There is no statement of when to use this tool versus alternatives such as lab_check (health validation) or lab_logs (log retrieval), nor any prerequisite or exclusion. The agent must infer routing from the name alone.

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

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

Goes well beyond the annotations by disclosing the full policy envelope (no privileged services, no host mounts but the lab folder, no Docker socket, 1 CPU/512m caps, no internet), the consequence (refused with the reason), and the networking gotcha (host can't reach its ports - use lab_exec from inside). The annotations only carry the safety flags; this text carries the real behavior.

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

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

The policy constraint is front-loaded and the confirmation requirement is placed last, which is sensible. It is a dense single paragraph with no wasted sentences, though the run-on policy clause is slightly heavy.

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

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

With an output schema present, return values need no explanation, and the description still covers behavior, policy limits, failure mode, networking caveat, and a human-confirmation step. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single 'lab' parameter is already documented as the name from list_labs. The description adds no further syntax or format detail about the parameter, so the baseline 3 applies.

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

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

States a specific verb ('Start') and resource ('a lab') and immediately scopes it to lab mode's policy. An agent can distinguish it from lab_down, lab_status, and the many container/compose siblings without opening any schema.

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

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

Gives a clear prerequisite - confirm with the person first, stating the services and images it will run - which is real usage guidance for a mutating tool. It does not, however, name alternatives (e.g. compose_up) or explicitly 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description still adds value by disclosing the default scope ('all unless running is true') and the returned fields, though it says nothing about ordering or size on a busy daemon.

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, scope stated first, chaining hint second. No filler and nothing buried.

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

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

With an output schema present, listing the returned fields is partly redundant, but the default-scope and identifier-chaining notes make the definition complete enough to call correctly. Only result ordering/volume behavior is left unstated.

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

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

Schema coverage is 100%, including the label pattern and example, so the schema carries the parameter burden. The description only adds the default behavior of the running flag ('all unless running is true'), which is a modest but genuine supplement.

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

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

States a specific verb and resource ('List Docker containers') plus the default scope ('running or not'), which cleanly separates it from inspect_container, container_stats, and other container siblings. The returned fields are enumerated, so an agent knows exactly what it gets back.

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

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

'Names and ids are what the other container tools take' tells the agent this is the discovery step feeding start/stop/inspect tools, which is real usage context. It stops short of naming an explicit alternative or exclusion (e.g. when to prefer inspect_container 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered by structured data. The description adds only the shape of the listing (id, repository, tag, size, created), and says nothing about filtering behavior or ordering beyond what annotations provide.

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

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

A single front-loaded sentence with no filler, but the trailing field enumeration duplicates part of the output schema and so is not fully earning its place.

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

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

With an output schema present, return values need not be explained, and the sole parameter is fully covered by the schema. The annotations carry the read-only profile, so the short description is nearly complete for a simple list tool; only usage/routing context is absent.

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

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

Schema description coverage is 100% and the single `dangling` parameter is documented in the schema; the description does not mention it at all. With one fully documented, non-required parameter, the baseline of 3 applies.

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

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

Specific verb ('List') plus a precisely scoped resource ('the local Docker images'), with the returned fields enumerated. This cleanly separates it from list_containers, list_volumes, list_networks and list_labs without needing to name them.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative routing guidance. Usage is implied by the name and the straightforward read-only nature of the operation, which fits the 'implied usage' level.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context about the folder location and the structure of each lab item. It does not describe return format or rate limits, but the output schema handles 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?

A single, front-loaded sentence that efficiently conveys the tool's purpose and a precise definition of what a lab is. No filler or redundancy.

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

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

Complete for a simple list tool with no parameters and an output schema. The description defines what a lab is, aiding interpretation of the output. It could be slightly more complete by hinting at the return shape, but the output schema already covers 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?

The tool takes no parameters, so there is no parameter semantics to clarify. The baseline for zero parameters is 4, and the description appropriately does not invent any.

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

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

The description states a specific verb ('List') and resource ('labs'), and defines what a lab is (practices in the labs folder, each with compose.yaml and optional lab.json). It does not explicitly differentiate from sibling tools like lab_status or list_containers, so it misses the top mark.

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

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

No guidance is given on when to use this tool versus alternatives such as lab_status or general listing tools. There are no prerequisites, exclusions, or contextual cues to help an agent choose correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without description help. The description adds the field set but says nothing about volume (all networks vs. running only), ordering, or pagination behavior beyond what the output schema provides. With annotations carrying the behavioral load, a 3 is appropriate.

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

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

A single sentence with the verb and resource front-loaded and a compact field list; no sentence 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?

With an output schema present, the description need not explain return values, and the annotations cover the safety profile; the definition is sufficient for a zero-parameter read tool. Minor missing context is whether filtering or scoping exists at all.

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

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

The tool takes zero parameters, so the baseline of 4 applies per the rules. The description correctly adds no parameter detail because there is none to add.

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

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

States a specific verb and resource ('List Docker networks') and enumerates the returned fields, so the agent knows exactly what this does. It does not explicitly distinguish itself from siblings like inspect_network or list_containers, 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?

Usage is implied: a zero-parameter list tool with nothing to configure means 'call it to enumerate networks'. However, there is no explicit when-to-use statement and no routing to inspect_network for per-network detail, so guidance is only inferable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description does not contradict it. The only added content is the returned field list, which is largely redundant given an output schema exists, and nothing is said about scope, pagination, or handling of unused/dangling volumes.

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

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

A single front-loaded sentence with zero filler; the verb and resource come first and the field enumeration follows immediately.

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

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

For a no-parameter list tool with annotations covering the safety profile and an output schema covering return values, the description contains everything an agent needs in order to call it correctly.

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

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

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

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

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

States a specific verb (List) and resource (Docker volumes), and even names the fields surfaced (name, driver, location). It is easily separable from inspect_volume, create_volume and remove_volume by the name alone, though the description 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?

No when-to-use guidance and no routing to alternatives such as inspect_volume for detail or disk_usage for consumption. Usage 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?

Annotations already flag destructive=true, but the description goes well beyond them: it warns volume data is permanently gone, states the operation can't be undone, discloses that a confirmation prompt naming the targets is shown, and explains that declining results in no action. That is exactly the interaction context an agent needs before calling a destructive 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?

Scope and consequences are front-loaded, and every sentence carries information (irreversibility, confirmation flow, freed-space reporting). The opening sentence is a long run-on with nested parentheticals that takes effort to parse.

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

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

With an output schema present, the description needn't detail return values, yet it still notes that freed space is reported. Combined with full parameter coverage and rich annotation backing, nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100% and includes enum and default documentation, so baseline is 3. The description still adds meaning, most notably that enabling volumes destroys their data and that allImages widens scope from dangling to all unused images.

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

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

The description gives a specific verb (remove) and enumerates exactly which resources are in scope: stopped containers, dangling images, unused networks, unused volumes, and build cache. This clearly separates prune from the targeted siblings like remove_container, remove_image, and remove_volume.

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 'what isn't in use' framing plus the conditional notes ('all unused ones with allImages', 'only when volumes is true') tell the agent when each mode applies. It never explicitly routes to a sibling for targeted single-resource deletion, so the alternatives are implied rather than stated.

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

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

Annotations already declare openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is largely covered. The description adds genuinely new context beyond annotations: the network/disk footprint and the requirement to confirm with the user before acting.

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

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

Two tight sentences: the action and default registry come first, the risk/confirmation note second, and the example is inline. No filler and nothing that repeats the schema or annotations.

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

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

With an output schema present, return values need not be explained. For a single-parameter pull, the description covers action, registry defaulting, example naming, and the user-confirmation obligation, leaving no material gap.

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

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

Schema description coverage is 100% and the schema already specifies tag format and registry-qualified names. The description still adds interpretive value by stating the default registry when none is given, which resolves an ambiguity the schema leaves open.

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 from its registry') plus a concrete example ('postgres:17') and the default behavior (Docker Hub unless another registry is named). The pull action is clearly separable from siblings like list_images, inspect_image, build_image and tag_image 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?

Gives a real precondition: 'Uses the network and disk: confirm with the person first,' which tells the agent when extra caution is warranted. It does not, however, name alternatives or note that run_container may implicitly pull, so the when-to-use-vs-sibling routing is only partially covered.

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?

Beyond the annotations (openWorldHint, non-destructive, idempotent), it discloses that the push may make the image public, that it relies on a docker login the person performed themselves, and that without credentials it reports the command the user must run in their own terminal. The security constraint (never ask for password or token) is exactly the kind of behavioral guidance annotations cannot carry.

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 default registry, then layered with prerequisites and safety rules; every sentence carries weight. The chain of short 'It ... It ...' clauses is slightly choppy but not padded.

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

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

An output schema exists so return values need no explanation, and the description covers the remaining gaps an agent needs: credential source, failure behavior without login, confirmation requirement, and public-visibility risk. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100% and the single parameter already documents the example format, so the baseline is high. The description still adds real meaning by explaining that the image string's registry prefix chooses the destination registry, which the pattern alone does not convey.

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 (upload a local image to its registry) plus the default-registry rule that determines the target destination. It also explicitly names tag_image as the related tool for renaming, so it is distinguishable from pull_image and siblings without opening a schema.

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

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

Gives explicit preconditions: rename with tag_image first if the image name starts with another registry host, and confirm with the person before publishing, naming the registry and tag. The alternative path and the required human confirmation are both spelled out rather than inferred.

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

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

Beyond the destructiveHint annotation, the description discloses that data is permanently gone and that the server asks the person to confirm, naming what will be removed, with no action if they decline. It also clarifies that force stops a running container first and volumes removes anonymous volumes.

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 action, then covers the two flags, the destructive consequence, and the confirmation flow in a compact sequence. Every sentence adds useful information.

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

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

Annotations already declare the destructive, non-read-only, idempotent behavior, and an output schema exists. The description completes the picture by explaining data loss, flag semantics, and the interactive confirmation safeguard.

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

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

Schema description coverage is only 33%, so the description carries important parameter meaning. It explains the two boolean options precisely: force stops a running container before removal, and volumes removes anonymous volumes.

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: remove a container. It is clearly distinct from sibling removal tools such as remove_network, remove_image, and remove_volume because the resource 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?

It explains what force and volumes do, which implies when those flags are useful, but it never states when to use remove_container instead of alternatives like stop_container. Usage is implied by the removal action rather than explicitly 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?

Adds real context beyond the destructiveHint annotation: it discloses a confirmation prompt that names what will be removed and that declining is a no-op, plus the recovery cost of re-pulling/rebuilding. The confirmation flow is not expressible in the annotations and is genuinely helpful.

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, then the recovery consequence, then the confirmation behavior. No filler; each clause carries operational meaning.

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 explained, and annotations already cover safety/idempotency. The description fills the remaining gaps: confirmation UX, decline behavior, and the re-pull/rebuild consequence. Complete for a two-param destructive tool.

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

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

Schema coverage is 50%; the image param is documented in the schema as 'name or id, as its list gives it', and the description compensates for the undocumented force param by explaining it removes even in-use images. It leaves the force default (false) to the schema, so it is strong but not exhaustive.

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

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

States a specific verb and resource ('Remove a local image') and scopes it against the sibling removes (container, volume, network) by qualifying the target as an image. An agent can distinguish it from remove_container/prune without opening the schema.

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

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

Explains the force case ('even if a stopped container uses it') and the consequence of removal ('has to be pulled or built again'). It does not explicitly route to alternatives such as prune for bulk cleanup, 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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing the human confirmation step, that the confirmation names what will be removed, and that declining results in no mutation at all. That is exactly the operational context an agent needs before invoking a destructive tool.

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

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

Two sentences, both load-bearing: the first gives the action and its precondition, the second gives the confirmation semantics. Nothing is redundant or buried.

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

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

With annotations covering the safety profile, a schema describing the parameter, and an output schema present, the description only needed to add the destructive-flow context, which it does. It could say slightly more about failure behavior (e.g. what happens if the network is missing), but nothing essential is absent.

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

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

Schema coverage is 100% and the single 'network' parameter is fully documented (name or id, format pattern). The description adds only the mild hint that the identifier is echoed in the confirmation prompt, so baseline 3 applies.

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

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

States a specific verb and resource ('Remove a network') plus a hard precondition ('no container may be attached'), which separates it instantly from create_network, inspect_network and list_networks. An agent knows exactly which operation this is without opening the schema.

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

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

The precondition 'no container may be attached' effectively says when the call will fail, so the agent knows to detach containers first. It does not name an explicit alternative (e.g. disconnecting containers), which is the only gap.

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

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

Annotations already declare destructiveHint/readOnlyHint, but the description adds genuinely new behavior: the cascade to contained files, irreversibility, a server-side confirmation that names the affected data, and a no-op outcome if the human declines. That decline path is critical context an agent cannot infer from the schema or annotations.

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

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

Two sentences, zero padding, with the destructive scope front-loaded before the confirmation caveat. Every clause carries information the agent needs.

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 no explanation, and the description covers destruction scope and the interactive confirmation. Minor gaps remain: it doesn't say whether removing a nonexistent volume succeeds (relevant given idempotentHint=true) or what happens when the volume is attached to a container.

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

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

One required parameter with 100% schema coverage, including the accepted name-or-id format and a pattern, so the schema carries the burden. The description adds nothing about the identifier beyond implying a single target; baseline 3 applies.

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

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

States a specific verb and resource ('Remove a volume') and immediately scopes the blast radius ('every file in it'), which distinguishes it from sibling remove_network/remove_container/remove_image that act on other resource types. No ambiguity about what the tool affects.

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 operational context that shapes when to call it: irreversibility and an interactive confirmation the caller must anticipate. It does not name alternatives (e.g. prune, create_volume) or state preconditions such as a volume being in use, so it stops short of an explicit when/when-not rubric.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true, and openWorld=false, covering the safety profile. The description adds a meaningful behavioral requirement not captured by annotations: human confirmation before performing the restart, plus the implication that the container must already 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?

Two short sentences, front-loaded with the action and followed by the confirmation requirement. Every element earns its place with no filler.

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

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

The tool is simple (one fully documented parameter, output schema exists, annotations cover safety traits). The description supplies the key behavioral extra (confirmation) and is sufficient for correct invocation, though minor operational details like downtime or behavior on stopped containers are absent.

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

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

Schema description coverage is 100% and the sole parameter 'container' is fully documented in the schema. The description adds no additional syntax or format details, so the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Restart an existing container'), which clearly distinguishes it from siblings like start_container and stop_container. However, it does not explicitly name or compare against those alternatives, so it falls short of the sibling differentiation seen in top-scoring examples.

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 includes a precondition ('Confirm with the person first'), which is useful, but it provides no guidance on when to choose restart over alternatives like stop_container + start_container or start_container alone. No when-not-to-use or alternative routing is offered.

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

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

Annotations only mark it non-read-only, open-world-ish and non-idempotent; the description adds the crucial traits the annotations don't carry – it mutates the machine and needs human confirmation, risky flags trigger a second server-side approval, images are auto-pulled, and a foreground run is stopped and removed when timeoutSeconds expires. That is exactly the behavioral context an agent needs before invoking.

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 and default behavior lead, then safety/consent, then isolation recipe, then timeout semantics – a sensible order with no filler sentences. The long comma-strung sentences (the dangerous-options list, the isolation recipe) are dense enough to slow parsing, so it falls just short of ideal.

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 23-parameter mutation tool this covers the decision-critical parts: consent requirement, escalation behavior, sandbox recipe, and foreground lifecycle. An output schema exists so return values need no explanation; the only remaining gap is that a handful of low-risk parameters get no narrative treatment beyond the schema.

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

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

With ~65% schema coverage over 23 parameters, the description supplies meaning for the risky and least-documented ones – privileged, pid, ipc, capAdd, devices, socket/root/home mounts – by naming what each grants the container, and explains 'none' for network, cpus/memory/pids throttling, readOnly, noNewPrivileges, and label-based cleanup. It leaves env, command, name, restart and workdir entirely to the schema.

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

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

States a specific verb and resource with scope: 'Create and start a container from an image (pulled if missing), in the background unless detach is false.' That wording separates it from start_container/restart_container, which act on an existing container, without needing to open 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 says to confirm with the person first, describes the server-side escalation for dangerous options and what happens on refusal, and points to list_containers for finding/remediating labeled sandboxes. It also gives the alternative path ('to try something without it reaching the computer, isolate it') with the exact settings – clear when and how, not just what.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context: it discloses the fields returned, notes that it includes configuration around confirmations and dangerous options, and explicitly says it contains no secrets.

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

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

A single, front-loaded sentence with no filler. Every listed item maps to the tool's returned server metadata.

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

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

Given the tool is a simple read-only, parameterless server-info operation, has an output schema, and has readOnly/openWorld annotations, the description is complete enough for correct selection and invocation. It does not need to explain return values because the output schema covers them.

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

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

There are no parameters, so parameter semantics are largely irrelevant. The schema is empty and the description does not need to compensate; baseline 4 applies.

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

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

States a specific verb ("Show") and resource ("this server's name, version, mode...") and enumerates the exact metadata returned. This clearly distinguishes server_info from sibling docker_info and other Docker/lab tools.

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

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

The description implies this is the tool for inspecting server identity and configuration, but it does not explicitly say when to use it instead of alternatives such as docker_info or check_requirements. Usage is inferable from the listed contents rather than stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds one genuinely non-structured behavior: a human confirmation is required before starting. It does not say what happens if the container is already running or what the call returns, so the added value is modest.

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 waste; the action is front-loaded and the confirmation caveat follows. 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?

With an output schema present, return values need not be explained, annotations cover safety, and the sole parameter is fully documented. The confirmation requirement is captured, but the relationship to sibling lifecycle tools (restart/run) is left unaddressed, leaving a small gap for a 43-tool suite.

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

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

Schema description coverage is 100% and the single 'container' parameter is fully documented in the schema with format constraints (pattern, minLength). The description adds no naming, ID-format, or resolution semantics beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Start an existing container'), which is clear enough to act on. However, it never distinguishes itself from the sibling restart_container, which is the tool an agent could most plausibly confuse it with, so it earns 4 rather than 5.

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

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

The only guidance is 'Confirm with the person first,' which is an approval instruction rather than a when-to-use rule. There is no statement of when to choose start_container over restart_container, run_container, or exec_in_container, and no precondition (e.g., the container must be stopped).

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

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

The 10-second clean-stop window and the human-confirmation requirement are behavioral facts not present in the annotations, which only state readOnly=false, idempotent=true, destructive=false. It does not say what happens after the 10 seconds elapse (force kill?) or how an already-stopped container is handled, but the core behavior is disclosed and consistent with annotations.

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

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

Two short sentences, front-loaded with the action and its timing, followed by the consent requirement. Nothing is wasted and there is no filler.

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

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

An output schema exists, so return values need not be explained, and the parameter is fully documented. The only gap is post-timeout behavior and how already-stopped containers are treated, which would round out an otherwise complete definition.

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

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

Schema coverage is 100% with a single well-documented `container` parameter (name or id, as returned by list). The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Stop an existing container") plus the operational detail of a 10-second grace period. It is clearly distinct from siblings like restart_container, remove_container, and start_container by verb, though it never names them.

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?

"Confirm with the person first" gives one concrete precondition for use, which is valuable. However, it offers no guidance on choosing stop_container over restart_container, remove_container, or a forced kill when a container is stuck.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior; the description adds genuinely new context by stating the image itself isn't copied (metadata-only) and prompting confirmation. It doesn't state permissions or what a re-tag replaces, so not a 5.

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

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

Two short clauses, front-loaded with the action and ending on the one operational caveat. 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?

With annotations and an output schema covering return shape and safety, the description supplies the key semantic point (no copy) plus a confirmation prompt. Sufficient for a simple 2-param operation, though permission/overwrite behavior is left implicit.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema; the description adds no syntax beyond loosely mapping 'name and tag' to them. Baseline 3 applies.

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

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

States a specific verb ('tag'/'give another name') and resource ('image'), and clarifies the operation is metadata-only, not a copy. It is clearly distinguishable from siblings like copy_to_container or build_image, though it names no alternative directly.

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 'Confirm with the person first,' a workflow caveat rather than a when-to-use-vs-alternatives statement. There is no direct tagging sibling to contrast against, so implied usage is adequate but thin.

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