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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value beyond that: the exact return envelope shape, what 'truncated' means, and the correct recovery action (raise tail rather than assume complete history). It doesn't mention pagination between re-runs, but the truncation contract is the key trait an agent needs.

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 [READ] tag and one-line purpose, then Args and Returns sections that each earn their place. Slightly list-like in the Args block, which repeats parameter names, but the added semantics justify it.

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

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

There is no output schema, yet the description documents the return envelope and the truncation flag's meaning, plus the recovery action. Combined with fully documented parameters, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: container_id (id or name), tail with its valid range 1..2000 and default 100, and target's meaning (config target name, omit for default). This fully compensates for the empty schema descriptions.

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

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

States a specific verb (tail), resource (container logs), and scope (stdout + stderr, last N lines). The [READ] marker and the log-specific framing make it clearly distinct from siblings like container_stats, inspect_container, and container_top.

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

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

Usage context is implied (log inspection for troubleshooting) and the re-run guidance when truncated is helpful, but it never says when to prefer this over inspect_container or container_stats, nor when not to use it. No alternatives are named.

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

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

readOnlyHint=true already covers the safe-read profile; the description confirms [READ] and adds useful behavior that results are ordered worst-first and include restart counts and exit codes. It does not describe limits, pagination, or output format, so it remains modest beyond the 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?

Front-loads the one-line purpose and keeps argument notes to the two parameters with defaults. No filler or repetition.

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

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

For a low-complexity, read-only summary tool with no output schema, the description supplies the needed purpose and both optional parameters. It could say more about the returned summary format, but not enough to block 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 0%, so the description must carry parameter meaning, and it does: all_states True inspects all containers while False limits to running; target names a configured target and can be omitted for the default. 'Target name from config' is slightly vague, preventing a 5.

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 (containers) and computed metric (restart-count + exit-code summary) with ordering (worst-first). A reader can distinguish it from restart_container or restart_loop_rca, though no sibling is named explicitly, so 4 not 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 description implies diagnostic use through 'summary' and 'worst-first' but never states when to choose this over restart_loop_rca, restart_container, or list_containers. No alternatives or exclusions are named.

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

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

readOnlyHint=true already declares this a safe read. The description adds one genuine behavioral trait beyond annotations — that it is a one-shot, non-streaming snapshot that returns immediately rather than blocking. It omits error conditions, prerequisites (e.g. container must be running), and units/pagination, 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?

Front-loads the [READ] tag and the core purpose in the first line, then a tight two-item Args block. No filler sentences, though the Args section is somewhat redundant with the already-legible parameter names.

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

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

For a simple two-parameter read tool with no output schema, the description covers what is returned (CPU%/memory% percentages) and how to call it. It still leaves gaps an agent might want — units, whether the container must be running, and how a missing/invalid container_id behaves.

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 carry the load, and it does: it explains that container_id accepts an id or name, and that target is a config target that defaults when omitted. This meaningfully compensates for the empty schema descriptions, though it adds no format examples.

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: a one-shot CPU%/memory% snapshot for a container. It is clear what it returns and its scope (stream=false), but it never names or contrasts with a sibling like container_top or inspect_container, so the agent must infer which stats tool fits.

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 '(stream=false)' and 'one-shot' framing implies when this is appropriate versus a streaming alternative, and 'omit for the default' gives default behavior for target. However no sibling tool is named and there is no explicit when-to-use/when-not guidance for selecting this over container_top or resource_pressure_analysis.

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?

readOnlyHint=true already tells the agent this is a safe read, and '[READ]' merely restates that. The 'like docker top' analogy does add useful behavioral context (a process snapshot rather than a stream or full inspect), but nothing is said about output shape, live-ness, or failure modes for a stopped container.

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 line of purpose followed by terse per-argument notes; the reader gets the operation and both parameters without a wasted clause. The Args block is somewhat redundant with the schema but keeps the definition self-contained.

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

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

For a two-parameter read tool with no output schema and readOnlyHint coverage, the definition is functional: both params are explained and the operation is clear. It still leaves the agent guessing how this differs from container_stats/inspect_container and what the response contains.

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 carries the burden and largely does: container_id is documented as 'Container id or name' (broader than the bare 'Container Id' title), and target is explained as a config target name with 'omit for the default', which the schema's anyOf/null default 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+resource: processes running inside a container, with the 'like docker top' analogy immediately pinning down the semantics. It distinguishes itself implicitly from container_stats and inspect_container, though it never names a sibling to contrast 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?

Only the '[READ]' prefix signals the read-only nature and thus the general context for using it. There is no statement of when to prefer this over container_stats, inspect_container, or container_logs, and no exclusions or prerequisites.

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

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

readOnlyHint=true already declares the safe read profile, so the bar is lower. The description adds useful context about what is returned (untagged images and reclaimable bytes) and the '[READ]' tag reinforces intent, but says nothing about permissions, per-target scoping behavior, or result ordering.

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?

Very short and front-loaded, with purpose stated before the Args block. The '[READ]' prefix and the 'Args:' header are mildly redundant given the annotations and single trivial parameter, but nothing is wasted.

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

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

For a single-parameter read-only list tool with no output schema, the description covers purpose, what is returned, and the parameter's meaning/default. It could be stronger by noting the relationship to prune_images and the absence of filtering options, but the essentials are present.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning, and it does: 'target' is a name from config and omitting it selects the default. That covers the one parameter's semantics and default behavior, though it doesn't say what the target actually scopes (host/context).

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

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

The description states a clear resource and scope: untagged (dangling) images plus reclaimable bytes, flagged as prune candidates. The 'dangling/untagged' qualifier inherently separates it from list_images and image_disk_usage, but no sibling is named explicitly, so differentiation is implied rather than stated.

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

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

Calling the output 'prune candidates' implies the tool is used to identify what prune_images would remove, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g. vs. list_images or image_disk_usage). Usage is inferable but left to the agent.

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 provide readOnlyHint=true, so the safe-read profile is covered. The description adds that it reports reclaimable bytes, a useful data point. But it doesn't disclose whether the scan is heavy, whether it requires a running daemon, or how it interacts with the config target.

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 [READ] tag and core purpose, then args. The single arg explanation is efficient, though the '[READ]' tag partly duplicates the readOnlyHint annotation.

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 no output schema, the description covers the resource, the key output metric, and the sole parameter's semantics. Missing only an explicit pointer to prune_volumes as the follow-up action.

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

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

Schema coverage is 0%, so the schema does not document the single target parameter at all. The description does explain that target is a 'Target name from config' and that omitting it yields the default, which compensates partially for the schema gap.

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

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

States a specific resource (dangling/unreferenced volumes) with the added metric (reclaimable bytes) and scope (prune candidates). Clearly distinguishes from siblings like list_volumes and prune_volumes by emphasizing 'unreferenced' and 'candidates'.

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 'prune candidates' implies this is the discovery step before prune_volumes, giving clear context. However, it does not explicitly name prune_volumes as the alternative or state when-not-to-use.

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

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

Annotations only declare readOnlyHint=true; the description adds '[READ]', the 'largest first' ordering, and the fact that injected payloads skip live calls. These are useful behavioral details beyond the annotations, though return format and any auth/prerequisite details are not covered.

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

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

Front-loaded with the tool's purpose, then usage and Args. There is slight redundancy between the first line and 'Sums dangling images, dangling volumes, and build cache', but the overall structure is efficient and easy to scan.

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?

Covers purpose, invocation modes, and all four parameters for a read-only aggregation tool with no output schema. Return shape is described as 'reclaimable-byte prune candidates, largest first', which is adequate but not exhaustive.

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 carry the full burden. Its Args section gives expected payload shapes for dangling_images, dangling_volumes, and df, and explains target/config semantics, providing substantial meaning beyond the bare schema types.

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 aggregation verb ('Sums') and the exact resources (dangling images, dangling volumes, build cache) and output ('reclaimable-byte prune candidates, largest first'). It distinguishes as read-only via '[READ]', but does not explicitly differentiate from siblings like resource_pressure_analysis or the prune 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 explains how to invoke it (pass payloads for pure analysis, or a target to pull live), which implies usage context. However, it does not compare this tool to alternatives such as resource_pressure_analysis or prune_images/prune_volumes, so when-to-use 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, so the safety profile is covered, and the description reinforces it with a [READ] marker. It adds the concrete return fields (total, shared, reclaimable), but says nothing about permissions, target resolution failure modes, or rate/refresh 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 compact segments: a one-line purpose with return fields, then a single Args entry. Fully front-loaded with zero 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 no output schema, the description usefully names the returned metrics (total, shared, reclaimable) and documents the lone optional parameter's default. For a simple read-only single-parameter tool this is nearly sufficient, missing only target resolution context.

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

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

Schema description coverage is 0%, so the description must carry the single parameter, and it does: 'target' is a name from config and omitting it falls back to the default. That default behavior is meaningful semantics not present in the schema, though it does not say what valid target names look like.

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 (read image disk usage) and names the underlying source (system/df) plus the return fields (total, shared, reclaimable). It is clear but does not differentiate itself from close siblings such as system_df or image_and_volume_bloat.

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

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

No guidance on when to choose this over system_df (overall system usage) or image_and_volume_bloat (bloat analysis), and no exclusions or prerequisites. Usage is only implied by the tool name and the [READ] tag.

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?

readOnlyHint=true already declares this as a safe read, and the '[READ]' prefix merely restates it. The description does add value by naming the returned sections (config, state, mounts, network), but omits auth requirements, size/pagination behavior, or any caveats. With annotations carrying the safety profile, this is adequate but not rich.

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

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

The purpose is front-loaded and the Args block is compact. The '[READ]' prefix is redundant with readOnlyHint=true, a minor waste, but overall the structure is efficient and skimmable.

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

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

There is no output schema, so the description usefully enumerates the inspect sections (config, state, mounts, network). For a read-only tool this is fairly complete, though it stops short of describing return structure or depth.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: container_id accepts an id or a name (added value over the bare string type), and target is explained as a 'target name from config; omit for the default'. 'Target' remains somewhat cryptic, but both parameters receive meaningful semantics beyond the schema.

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

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

States a specific verb and resource ('Full inspect of one container') and enumerates what it returns (config, state, mounts, network), which cleanly distinguishes it from the inspect_image/inspect_network/inspect_volume siblings. An agent can identify the target resource 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 '[READ]' tag and 'Full inspect' imply a read-only diagnostic context, but there is no explicit when-to-use guidance or contrast with list_containers, container_stats, or container_logs. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful behavioral note that output includes build history (layers, sizes, commands), which is real added context. However, it says nothing about error behavior for missing images, performance on large images, or output format. A 3 reflects modest added value beyond annotations.

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

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

Front-loads the read semantics and purpose in one bracketed phrase, then lists args compactly. The 'Args:' section is a bit redundant with the schema, but it's short and earns its place by clarifying the opaque 'target'. No wasted 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 2-param read tool with no output schema and only readOnlyHint, the description is adequate but not complete: it doesn't explain what a 'target' actually is in this system, nor how to interpret the returned layer/history data. An agent can call it, but may mis-set 'target' without config context. An output schema is absent, so the description could do more to set expectations for return shape.

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 carries the parameter-explanation burden. It does add meaning for both params: 'image_id' is 'Image id or name:tag', and 'target' is 'Target name from config; omit for the default'. This is genuinely helpful, but the target explanation is thin (what config? what is a target?) and 'name:tag' format could be clearer. Baseline for 2 params is 4, but the shallow target note pulls it to 3.

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

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

Clear verb 'inspect' and resource 'image', and the parenthetical '(layers, sizes, commands)' sharpens what is returned beyond a generic inspect. It distinguishes itself from siblings like list_images or image_disk_usage by specifying deep, layered detail. It does not explicitly name a competing sibling, so it falls short of a 5.

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

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

The '[READ]' tag and parenthetical hint imply this is the tool for deep image introspection, and the 'target' arg note ('omit for the default') gives a small usability cue. But there is no explicit when-to-use vs image_disk_usage or dangling_images, nor any prerequisite (e.g., image must exist locally). Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint=true, and the "[READ]" tag is consistent with that. The description adds a light behavioral signal by listing the inspected facets, but discloses nothing about failure modes (unknown/ambiguous network name) or resolution order between id and name. With annotations covering safety, a 3 fits.

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 one-line summary followed by a compact Args block; no filler sentences. The "[READ]" prefix is mildly redundant with the readOnlyHint annotation but costs little.

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

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

With no output schema, the description appropriately names what the inspection returns and documents both inputs, including the nullable target default. Only the error/ambiguity behavior for a non-existent or non-unique network name is unaddressed.

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

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

Schema description coverage is 0%, so the description carries the full burden and does add real meaning: network_id accepts "id or name" (broader than the schema title implies) and target is "Target name from config; omit for the default." Both parameters are covered with behavior the schema does not express.

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 pair ("Inspect one network") and enumerates what the inspection surfaces (driver, IPAM subnet/gateway, attached containers). The singular "one network" implicitly distinguishes it from the sibling list_networks without needing the schema.

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

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

Usage is only implied: pass a network id/name to get detail on that single network. It never states when to prefer this over list_networks or inspect_container-style siblings, nor any precondition such as the network needing to exist. Adequate but with a clear routing 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?

The [READ] marker and readOnlyHint annotation together make the safety profile unambiguous, and the description goes beyond the annotation by disclosing what information is retrieved (driver, mountpoint, options, usage). It does not mention error behavior for a missing volume, which is the main 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?

Front-loaded with the operation and its scope, then a compact Args block. The bracketed [READ] tag is slightly redundant with the readOnlyHint annotation, but overall there is little waste.

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

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

With no output schema, the description usefully summarizes the returned fields, and both parameters are explained. Complete enough to call correctly; only missing guidance on error cases and whether the volume must exist.

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 carry parameter meaning — and it does, documenting both params: name as the volume name and target as a config target that defaults to the default when omitted. That resolves the anyOf/null default ambiguity the schema leaves unexplained.

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 ("Inspect one named volume") and even enumerates the returned facets (driver, mountpoint, options, usage). It implicitly distinguishes itself from list_volumes/dangling_volumes by scoping to a single named volume, though it never names those siblings explicitly.

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

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

Usage is only implied by the phrase "one named volume" — the agent can infer this is the detail view for a volume it already knows by name, versus list_volumes for discovery. No explicit when-to-use, prerequisites, or failure conditions (e.g., volume not found) are provided.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context: it is a '[READ]', it derives stacks from a specific label, it works across docker/podman targets, and it defines the rollup semantics (healthy=all running, degraded=some, down=none). That is useful disclosure beyond the 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?

Front-loaded with the core action, then mechanism, then args; no filler sentences. Slightly loose formatting (trailing newline, inline Args block) but 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?

With no output schema, the description does the work of explaining what comes back (per-stack health rollup with three states) and covers the single optional parameter. Adequate for a read-only listing tool, though it omits any mention of pagination or ordering.

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

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

Schema coverage is 0% (the 'target' property has only a type and default), so the description must compensate, and it does: 'Target name from config; omit for the default' explains both the value source and the default behavior, which the schema does not.

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 ('Group containers into Compose projects') plus the distinguishing mechanism: reconstruction from the 'com.docker.compose.project' label over the Docker-compat layer. The '(no Portainer needed)' note implicitly separates it from the Portainer-based list_stacks sibling, though it never names that sibling.

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

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

No when-to-use guidance or alternatives are given. The closest thing is the remark that it targets docker OR podman without Portainer, but that is a capability statement, not routing guidance against list_stacks or stack_detail.

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?

readOnlyHint=true already covers the safety profile, and the '[READ]' prefix merely restates it. The description does add genuine output context the annotations lack ('bucketed by state, with compact rows'), but says nothing about ordering, truncation, or what a compact row contains.

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

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

Front-loads the verb+resource+output shape, then uses a compact Args block with no filler sentences. Slightly terse on the target parameter's meaning, but nothing is wasted.

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

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

For a read-only two-param list tool with no output schema, the description covers both parameters and gives a sense of the return structure (bucketed by state). It is sufficient to invoke correctly, with only minor gaps around state values and result ordering.

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 carries the burden and does so for both params: all_states is defined (True = all containers, False = running only) and target is defined (config target name, omit for default). Meaning is added beyond the bare anyOf/boolean 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 ('List containers') plus output shape ('bucketed by state, with compact rows'), which distinguishes it from inspection siblings like inspect_container and container_stats. It does not explicitly name a sibling alternative, so it stops short of a 5.

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

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

Usage is only implied through the all_states flag semantics (True = all, False = running); there is no statement of when to reach for list_containers versus list_pods, inspect_container, or container_restart_summary. The default behavior is clear but the routing guidance is absent.

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, so the safety profile is covered, and the "[READ]" tag merely restates it. The description does add useful context (it needs a configured portainer target), but gives no pagination, rate-limit, or response-shape detail.

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

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

Front-loads the read tag and resource meaning, then the prerequisite, then args. The Args block is slightly boilerplate for a single optional param but nothing is wasted.

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

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

For a simple single-param read tool with no output schema, the description supplies both the returned fields and the target requirement, which is sufficient 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 0%, so the description must compensate, and it does: it identifies the arg as a target name from config with a defined default when omitted. That meaning is absent from the bare schema property.

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 (Portainer endpoints), clarifies that endpoints are managed hosts, and enumerates the returned fields (id, name, type, status, url). No sibling tool lists endpoints, so an agent can route to it unambiguously.

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

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

"Requires a portainer target" gives a precondition, and the target arg note explains the default-omission behavior. However, it offers no when-to-use/when-not framing or comparison to any alternative, leaving usage 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?

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description adds useful context beyond annotations: the [READ] marker, the sort order (largest first), and the fields returned (tags, size, dangling). It omits auth needs, pagination, and return-format details, so it adds only moderate 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?

Purpose is front-loaded in the first sentence, followed by a compact Args block. No filler or redundancy; every line conveys usable information.

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

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

For a simple read-only listing with annotations covering safety and no output schema, the description covers purpose, both parameters, ordering, and returned fields. Adequate for correct invocation, with only minor gaps like pagination or result volume.

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 carries the full param burden and does so well: all_images is explained as including intermediate layers vs top-level only, and target as a config target name defaulting to the standard. Both parameters gain meaning the bare schema lacks.

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 (images) plus what the listing surfaces (tags, size, dangling) and how it is ordered (largest first). It is clearly distinguishable from inspect_image, but it never explicitly contrasts itself with siblings like dangling_images or image_disk_usage that also touch image data.

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

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

No when-to-use or when-not-to-use guidance is given. With many overlapping siblings (dangling_images, image_disk_usage, inspect_image), an agent gets no routing help about when this broad listing is preferred over a more targeted tool.

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, so the safety profile is covered; the description usefully adds that output is grouped by driver. It says nothing about pagination, volume of results, or error behavior on an unknown target, so added value over annotations 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?

The single-line purpose is front-loaded and the Args block is compact with no filler. Slightly more verbose than strictly needed for a one-parameter tool, but nothing is wasted.

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

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

For a simple read-only list tool with no output schema, the description covers purpose, read semantics, output grouping, and the only parameter's behavior. The absence of any statement about result size or empty result handling is a minor gap.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: 'target: Target name from config; omit for the default' explains origin, meaning, and the omission/default case. It stops short of naming valid target values, but it meaningfully compensates for the empty 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 ('List Docker networks') and adds a distinguishing behavioral note ('bucketed by driver'), which separates it from inspect_network. However, it does not explicitly name or contrast with the sibling inspect_network, so differentiation is implied rather than stated.

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

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

The '[READ]' prefix implies this is a non-mutating enumeration tool, and 'omit for the default' implies the default-target case, but there is no explicit when-to-use guidance or comparison to inspect_network or other list_* tools. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the '[READ]' tag is redundant. The description earns credit beyond that by disclosing the failure mode on unsupported targets and the underlying libpod API, which an agent needs to interpret errors correctly.

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

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

Front-loads the verb and resource, then adds the Podman-only caveat and argument note. The middle explanatory sentence is slightly long but each part informs correct invocation, so little 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 no output schema, the description compensates by listing the returned fields. Combined with the target requirement and error behavior, an agent has everything needed to call the tool and interpret results.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: it explains that 'target' is a config target name and that omitting it uses the default. That resolves the parameter's meaning and default behavior not present in the bare 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 + resource (List Podman pods) and enumerates the returned fields (id, name, status, member containers). It also distinguishes itself from the Docker-oriented siblings by flagging the Podman-native concept and the absence of a Docker equivalent.

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

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

Gives a clear precondition ('Requires a podman target') and an explicit when-not condition (on docker/portainer it returns a teaching error). It does not, however, name a concrete alternative tool for non-podman targets, so it falls short of full routing guidance.

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

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

readOnlyHint=true already covers the safety profile, so the redundant "[READ]" tag adds nothing. What does add value: it discloses the target dependency and, with no output schema present, lists the fields the call returns. Minor gaps remain (pagination, 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?

Tight and front-loaded: read indicator, resource, returned fields, prerequisite, then an Args block. Nearly every fragment earns its place; only the "[READ]" tag duplicates the annotation.

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

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

For a single-optional-param list tool with no output schema and readOnly annotations, the description covers the prerequisite, the default behavior, and the returned shape. It is complete enough to invoke correctly, missing only sibling-routing detail.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does: it explains that target is a "Target name from config" and that omitting it uses the default. That is more than the bare string/null schema conveys.

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-tagged read operation on a specific resource (Portainer stacks, Compose/Swarm) and enumerates the fields returned (id, name, type, endpoint, status). It is largely differentiable from siblings like list_compose_stacks and stack_detail, though it doesn't explicitly contrast itself with 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?

Names the sole prerequisite ("Requires a portainer target"), which is useful context. However it gives no explicit when-to-use versus list_compose_stacks/stack_detail, so routing 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?

readOnlyHint=true already tells the agent this is a non-destructive read, so the '[READ]' tag is largely redundant. The description does add one piece of value beyond annotations by naming the returned fields (name, driver, mountpoint, scope), but it says nothing about ordering, filtering behavior, or result size.

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

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

Two compact lines with the purpose front-loaded and the return fields and argument explained without filler. The bracket tag is slightly redundant against the annotations, which is the only minor waste.

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

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

With no output schema, naming the returned fields is exactly the right compensation, and the single argument is fully explained. For a simple read-only listing the definition is essentially complete, though it omits any hint about ordering or pagination of results.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics, and it does: 'target' is documented as a 'Target name from config' with 'omit for the default.' That explains both the value source and the defaulting behavior that the bare anyOf/null schema does not.

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 named volumes') and enumerates the returned attributes, which distinguishes it from inspect_volume and dangling_volumes by implication. The scoping word 'named' is the only signal separating it from the dangling-volume sibling, so differentiation is present but implicit rather than explicit.

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 dangling_volumes, inspect_volume, or list_images, and no prerequisites or exclusions are given. The '[READ]' marker implies a safe read but does not route the agent among the many sibling listing 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?

The '[READ]' prefix and 'one-shot' language add context beyond the readOnlyHint=true annotation, and the triage framing is useful. However, it doesn't state whether the call is expensive, whether it aggregates live or cached data, or any rate/permission constraints – moderate added value for a read-only tool.

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

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

Front-loads the READ tag and the one-shot scope, then the triage instruction, then the single arg. No filler sentences; everything earns its place.

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

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

For a one-param read-only triage tool with no output schema, the description covers purpose, placement in workflow, and the parameter. Minor gap: no indication of what the rollup output looks like, but no output schema exists to explain it.

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

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

The schema has 0% description coverage, so the description must carry the single 'target' parameter. It does state 'Target name from config; omit for the default,' which meaningfully explains the parameter and the omit-default behavior, compensating for the bare 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 (overview/rollup) and enumerates exactly what is returned: version, container state rollup, and disk. This distinguishes it from single-resource siblings like inspect_container or system_version.

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

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

Explicitly says 'Call this first to triage a container host before drilling into a specific container, image, or volume,' naming the alternative workflow and the decision point that selects this tool.

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=false, so the baseline is low. The description adds genuine context beyond them: the '[risk=high]' marker, the explicit 'No undo' reversibility warning, and the fact that dry_run enumerates removals plus reclaimable bytes before any change occurs.

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 safety banner is front-loaded on line one and the args list is scannable. There is mild redundancy in explaining dry_run twice (once in the prose, once under Args), but nothing is wasted at length.

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

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

With no output schema, the description is responsible for return semantics and does describe what dry_run returns (the list of images and reclaimable bytes). Combined with the destructive warning and full parameter semantics, an agent has nearly everything needed; only the target's accepted values remain unclear.

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 carries the full burden and largely delivers: it documents all three parameters, gives defaults ('True (default)' for dangling_only, false for dry_run), and clarifies the semantic difference between untagged images and images unused by any container. The target parameter is only described as 'Target name from config', leaving its valid values unspecified.

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 ('Prune images') plus the default scope ('dangling by default'), which is enough for an agent to distinguish it from list_images/dangling_images purely by intent. It stops short of explicitly naming siblings like dangling_images or prune_volumes, so it is clear but not fully differentiated.

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

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

It explains the two modes of dangling_only (untagged only vs. unused by any container) and describes dry_run as the safe preview path, which implies when to use each. However, it never routes the agent to alternative tools (e.g. dangling_images to merely list untagged images) nor states prerequisites, so the guidance is implied rather than explicit.

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

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

Goes well beyond the annotations: 'No undo', 'Irreversible', the Docker >=23.0 default behaviour, the warning that named volumes usually hold data someone meant to keep, and the detail that a default-scoped dry_run still reports named unused volumes via alsoUnusedNamed* rather than hiding them. The annotations (destructive=true, readOnly=false) are confirmed and substantially enriched.

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

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

Front-loads the WRITE/risk/no-undo signal, then the behavioural nuance, then a clean Args block — every section earns its place and there is no filler. The middle paragraph is dense with parentheticals, but the information is load-bearing rather than decorative.

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

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

For a destructive, no-output-schema tool with 0% schema coverage, the description covers the risk profile, the flag-dependent scope of destruction, and what dry_run returns (removals plus reclaimable bytes). Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it defines all three parameters: all_unused (remove NAMED unused volumes, irreversible), dry_run (list what would be removed plus reclaimable bytes), and target. target is only glossed as 'Target name from config; omit for the default', which is thinner than the other two, keeping this just short of a 5.

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 (prune unreferenced volumes) with a scope qualifier and a risk flag up front. It clearly distinguishes itself from read-only siblings like list_volumes, inspect_volume, and dangling_volumes, which merely report the same space. An agent can tell what it does and what it does not touch 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 crucial when-to-use nuance: Docker only prunes anonymous unused volumes by default, and named volumes survive unless all_unused is set, so the agent knows the flag changes the blast radius. It also explains how dry_run is scoped by the same flag. It stops short of naming sibling alternatives (e.g. dangling_volumes for inspection) as an explicit routing signal.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description still adds meaningful context beyond them: 'No undo', the audit capture of the stack definition beforehand, and the requirement of a portainer target.

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 [WRITE][risk=high] tag and the 'No undo' warning are front-loaded, and the Args block is compact. Minor redundancy between 'Redeploy (recreate)' and the later audit sentence, but nothing wasteful enough to harm the definition.

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 non-idempotent mutation with an output schema absent, the description covers the destructive consequence, the irreversibility, the dry-run escape hatch, and every parameter. Sufficient for an agent to call it correctly; only the preview's return shape 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 description coverage is 0%, so the description carries the load and does so: it documents all four params, including the fallback semantics for endpoint_id ('omit to use the stack's own') and target ('omit for the default'). It stops short of format examples for stack_id.

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 ('Redeploy (recreate) a Portainer stack') and immediately distinguishes it from plain restarts via the redeploy semantics. An agent can tell this apart from restart_container or stack_detail without opening another 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 conditional usage for one param ('Pass dry_run=True to preview') and a prerequisite ('Requires a portainer target'), but never names when to choose this over alternatives such as restart_container or the undo_list/undo_apply pair. Usage is implied rather than routed.

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=false, but the description adds substantial context beyond them: the full inspect JSON is captured before deletion for the audit trail, there is no clean inverse, and force implies SIGKILL semantics. These are exactly the operational details an agent needs before an irreversible action.

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

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

Front-loads the write/risk tag and the irreversibility warning ahead of the args list, so the most important information lands first. The Args block partially restates schema property names, but each entry adds real semantics, so the redundancy is minor and earned.

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

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

For a destructive tool with no output schema, the description covers irreversibility, audit behavior, preview mode, and all five parameters. It stops short of describing post-conditions or error behavior (e.g., removing a nonexistent container), which is the only remaining gap.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden — and it does: container_id accepts an id or name, force maps to SIGKILL on a running container, remove_volumes targets anonymous volumes, dry_run previews, and target selects the config target. Each parameter gains meaning not present in the schema.

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

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

States a specific verb and resource ('Remove a container') with an explicit risk/op type prefix, and the parenthetical '(captures full inspect first)' plus 'No undo' separates it from reversible siblings such as stop_container or restart_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?

Gives clear usage context ('No undo', 'Pass dry_run=True to preview'), which tells the agent when this tool is appropriate versus a safe preview. It does not, however, explicitly name stop_container or other non-destructive alternatives that would be the right choice when removal is not intended.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description adds substantial behavior: one-shot vs live collection, the near/over classification logic, worst-first ranking, attached recommendations, and that every row carries its numbers. It stops short of describing pagination or edge cases, but the disclosure is well beyond the 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?

The one-line summary is front-loaded with the key scope before the mechanics, and content is dense with little filler. The Args block is somewhat mechanical but each entry adds real semantic value, so it earns its length.

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

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

With no output schema, the description carries return-value burden and does so reasonably, describing classifications, recommendations, ranking, and per-row numbers. For a read-only analytical tool with all params documented it is close to complete, though it omits any note on empty results or the exact response structure.

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 carry the full load, and it does: it documents all four params, explains cpu_threshold/mem_threshold defaults and semantics, describes the injected 'samples' row shape (id, name, cpuPercent, memPercent, memUsageBytes, memLimitBytes) and that it skips live collection, and clarifies 'target' is a config name with a default.

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

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

Opens with a specific verb+resource ('Rank containers by CPU/memory pressure vs their limits') plus the differentiator '+ recommend', which separates it from sibling read tools like container_stats or container_top that return raw samples without ranking or remediation. An agent can grasp the analytical nature of the tool without opening the schema.

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

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

The description implies usage (analyze which containers are under pressure, with injected samples for offline analysis) and the '[READ]' tag conveys safety, but it never states when to choose this over container_stats/container_top or any exclusion conditions. Usage is inferable but not 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?

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds genuinely new context: prior state is captured for audit, there is no meaningful inverse so no undo is recorded, and dry_run previews the action. This is meaningful disclosure beyond the structured hints.

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 risk tag and purpose, then a concise behavioral note, then a tidy Args block. Every line earns its place; only slight redundancy in restating default values already in the schema.

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

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

No output schema exists, and for a destructive 4-param mutation the description covers the safety profile, undo behavior, preview mechanism, and all parameters. It is complete enough to invoke correctly, missing only explicit routing among sibling lifecycle tools.

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

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

With schema description coverage at 0%, the description carries the burden and documents all four parameters: container_id (id or name), timeout (graceful stop window, default 10), dry_run (preview semantics), and target (config name, omit for default). It compensates well for the empty schema descriptions, though no extra format detail is given.

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 ('Restart a container') and is immediately distinguishable from siblings like stop_container and start_container. The [WRITE][risk=medium] tag reinforces the operation class up front.

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 preview path via dry_run=True, which is useful guidance. However, it never states when to restart vs. alternatives like stop_container+start_container or update_container, nor any preconditions, so usage context is implied rather than explicit.

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

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

Annotations only declare readOnlyHint=true. The description adds rich behavioral detail: it inspects restart count + exit code, flags containers by restartCount >= threshold or restarting/dead or non-zero exit, maps exit codes to causes (137 OOM/SIGKILL, 143 SIGTERM, 139 segfault, 127 bad entrypoint), attaches log tails, and notes every ranking carries its numbers. This is substantial context beyond the 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?

Front-loaded with [READ] and purpose, then structured with an Args section. Information is mostly useful, but the phrase 'The flagship restart RCA' is promotional fluff. The description is appropriately sized for a complex diagnostic tool, though slightly verbose.

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

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

No output schema exists, but the description explains what is returned: flagged containers, attached cause/action, log tails, and numeric rankings. Combined with full parameter descriptions and the readOnly annotation, an agent has enough 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?

Schema description coverage is 0%, so the description must carry the burden. It documents all four parameters: restart_threshold with default and meaning, containers with nested fields and note that it skips live collection, logs_by_id with shape, and target as config name with omit-for-default semantics. This fully compensates for the schema gap.

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

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

States a specific verb and resource: 'Find crash-looping containers and map each to a cause + action.' It explains the inspection inputs (restart count, exit code), the flagging logic, and the outputs (cause, action, log tail), distinguishing itself from sibling action tools like restart_container. An agent can tell this is a diagnostic RCA tool.

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 two operational modes: pass 'containers' for pure analysis or 'target' to pull live. This gives clear context for invocation. However, it does not explicitly name alternatives (e.g., restart_container) or state when not to use it, so it falls 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?

The '[READ]' tag and readOnlyHint annotation already signal a safe read, so the description needn't re-explain safety. It adds modest value by naming the returned sections (env, entrypoint, resource control), but says nothing about failure modes, permissions, or missing-stack behavior.

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

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

Front-loaded with the read tag and the core purpose, followed by a compact Args block. No filler, though the two-sentence split into prose plus an arg list is slightly 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 no output schema, the description should describe returns, and it only gestures at them by listing sections. Annotations cover the read safety profile. Adequate for a simple read, but an agent still lacks detail on the response shape.

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 carry the params, and it does: stack_id is defined as the Portainer stack id, and target is explained as a config name with 'omit for the default'. This adds real semantics beyond the bare schema, though stack_id's expected format is not clarified.

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: retrieving one Portainer stack 'in detail', and enumerates what detail means (env, entrypoint, resource control). The singular 'one stack' distinguishes it from list_stacks/list_compose_stacks, though no sibling is named explicitly.

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

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

States a prerequisite ('Requires a portainer target') that helps an agent pick the right target. It does not say when to reach for this versus list_stacks or inspect-style siblings, so usage remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=true, so safety profile is covered. The description adds value beyond that: the [WRITE] marker, a risk rating, the non-idempotency implication of 'stopped container' scope, and the dry_run preview path. It does not explain behavior when the container is already running. Note the mild tension between the benign 'start' framing and destructiveHint=true, but the description does not assert non-destructiveness, so it is not a contradiction.

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

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

Front-loads the operation class and risk marker before the body, and each sentence carries needed information. The Args block is slightly redundant against the surrounding prose (dry_run is mentioned twice) but is not padding since the schema documents 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 no output schema and only 3 parameters, the definition covers what the tool does, when it applies, the inverse operation, and the preview mechanism. It omits edge-case behavior (container already running, permission requirements) and any return-value expectation, keeping it short of fully complete for a mutation tool.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: container_id (id or name), dry_run (preview semantics), and target (config target, optional with a defined default). This is a clear example of the description compensating for an undocumented schema, though it stops short of format examples for container_id.

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

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

Specific verb+resource: 'Start a stopped container' clearly distinguishes it from siblings stop_container and restart_container. It also names its inverse ('Inverse: stop it'), so an agent can place it precisely in the lifecycle 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?

States the condition of applicability ('a stopped container'), signals the write/risk profile, and tells the agent how to preview via dry_run=True. It does not explicitly route the agent to restart_container for an already-running container, so the alternative-selection guidance is implicit rather than spelled out.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds real value beyond them: it explains that prior running state is captured so the harness can record a start undo, and it exposes a non-destructive dry_run preview. It also clarifies the timeout is the graceful-stop window before a kill. It does not say what happens when the container is already stopped.

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 operation class and purpose are front-loaded in the first line, followed by a tight Args block. The only waste is dry_run being described twice (inline and in the Args list), but overall it is well-sized for a 4-parameter write tool.

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

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

For a mutating tool with no output schema, the description covers parameters, safety class, undo capture, and a preview mode, which is most of what an agent needs. The remaining gap is behavior on an already-stopped container and how errors surface, but the essential calling information is present.

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

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

With 0% schema description coverage, the description carries the full burden and does so: container_id is defined as id-or-name, timeout is given units, default, and kill semantics, dry_run is explained, and target is described as a config name that can be omitted. Each of the four parameters gains meaning beyond the bare schema types.

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

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

States a specific verb+resource ("Stop a running container") and pre-empts the sibling ambiguity by naming the inverse operation (start_container). The [WRITE][risk=medium] tag classifies the operation class up front, so an agent can distinguish it from restart_container or remove_container 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 names the inverse action and advertises a dry_run preview path, which implies the safe-exploration flow, but it never states when to prefer stop over restart_container or when stopping is inappropriate. Usage 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?

readOnlyHint=true already establishes this as a safe read, so the '[READ]' prefix is largely redundant. The description does add real value by enumerating what the breakdown covers (images, containers, volumes, build cache), which tells the agent the scope of the returned data.

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 operation and its categories, then the arg, with no filler. Slightly formulaic Args block, but every line 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?

No output schema exists, but the description names the categories of data returned, which is sufficient for an agent to know what it gets back. A one-parameter read-only tool is adequately covered; only multi-tool disambiguation 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 0%, so the description must carry the parameter meaning, and it does: 'target: Target name from config; omit for the default.' That explains provenance and the omit-for-default behavior that the schema only implies via default=null.

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 and verb-like operation ('Disk-usage breakdown') and enumerates the four categories reported (images, containers, volumes, build cache). This is clearer than a bare name, though it does not distinguish itself from nearby siblings like image_disk_usage or image_and_volume_bloat.

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?

Only guidance given is about the target parameter default; there is no when-to-use or when-not-to-use guidance, and no routing to alternative disk-usage siblings such as image_disk_usage or image_and_volume_bloat.

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 readOnlyHint annotation already covers the safety profile, so the description's job is to add context beyond that. It does: it discloses the aggregation behavior (rolled up by type+action), the exact return envelope, and — most usefully — the truncation behavior plus the remedy ("narrow the window with a smaller since"). It stops short of stating whether the window is measured against event timestamps or receipt time.

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

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

Front-loads the one-line purpose before the structured Args and Returns blocks. Every element is load-bearing: no restatement of the name, no filler, and the truncation caveat is tied directly to the parameter that fixes it.

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

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

There is no output schema, so documenting the return envelope ("events"/"returned"/"limit"/"truncated"/"total") is necessary and it is done. Combined with the readOnlyHint annotation, full parameter coverage, and explicit truncation handling, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly meets it: it gives the since range and default (1..86400, default 3600), enumerates valid event_type values (container/image/volume/network) that are absent from the schema, and explains that target comes from config. The target explanation is the weak spot — "Target name from config" doesn't tell an agent where to find valid values.

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 ("Recent daemon events") plus the scoping semantics ("over the last N seconds, rolled up by type+action"), which tells the agent exactly what granularity it will get back. No sibling tool covers daemon events, so this is unambiguously distinguishable and even self-labels as "[READ]".

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 per-parameter filtering guidance ("omit for all", "omit for the default"), which implies usage, but never states when to reach for this tool instead of overview, system_df, or system_info. No exclusions or alternatives are named, so the agent must infer the scenario.

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 readOnlyHint=true annotation already establishes the safe-read profile, and the '[READ]' prefix merely restates it. The description does add value by enumerating the information categories returned, which partially compensates for the absent output schema. It says nothing about scope (local vs remote daemon), error behaviour, or how the target config is resolved.

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 operation and the returned fields in one line, followed by a short Args block for the only parameter. No padding or filler sentences; the '[READ]' tag is mildly redundant with the annotation but harmless.

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

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

For a single-optional-parameter, read-only tool with no output schema, the description covers what is fetched and how the parameter resolves the target. Remaining gaps — daemon scope, pagination/volume limits, failure modes — are minor for this tool class.

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

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

Schema coverage is 0% and the schema only shows an unconstrained string-or-null 'target' with default null. The description compensates by explaining that target is a name drawn from config and that omitting it selects the default — the essential semantics for the single 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+resource ('Daemon info') and enumerates the content returned: container/image counts, storage driver, kernel, resources. That is enough for an agent to know what it retrieves. It does not, however, distinguish itself from near-neighbours like system_version, system_df, or overview, which an agent could also plausibly pick for host-level facts.

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

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

The description gives no when-to-use guidance and names no alternatives, despite siblings (system_df, system_version, overview) covering overlapping host/daemon information. The only routing hint is 'omit for the default', which is a parameter default, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' prefix is consistent with that. The description adds useful disclosure of the payload contents (API version, Go version, components), which partly compensates for the absent output schema, but says nothing about auth, error behavior, or whether the daemon must be reachable.

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

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

One tight headline sentence plus a labeled Args block, front-loaded with the operation and its read-only nature. Nothing is padded, though the section header and blank line formatting are slightly heavier than needed for a single optional argument.

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

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

For a one-optional-parameter read tool with no output schema, the description covers the operation, its read-only nature, the returned fields, and the parameter's meaning. The remaining gap is the lack of routing guidance relative to system_info/system_df, which is minor for such a simple 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 0%, so the description must carry the parameter burden, and it largely does: 'target: Target name from config; omit for the default' explains that the value is a configured target name and that omission selects the default. That is more meaning than the bare 'Target' title in the schema, though it does not give examples of valid target names.

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: return Docker version details, enumerating the fields (API version, Go version, components). This is clearly separable from neighbors like system_info, system_df, and system_events. It stops short of explicitly contrasting with those siblings, so it earns a 4 rather than a 5.

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

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

There is no statement of when to reach for this tool versus system_info or system_df, which are the obvious near-neighbors. The only usage-adjacent note, 'omit for the default', concerns the target argument rather than tool selection. An agent must infer the boundary from the name alone.

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

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

Annotations already declare non-read-only, non-idempotent and destructive, and the description adds meaningful context beyond them: the inverse runs through its own governed/audited tool, dry_run previews without executing, and 'a token can only be applied once' explains the one-shot semantics. It does not say what happens on partial failure or whether the undo is itself reversible, keeping it below a 5.

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

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

Front-loaded with the [WRITE][risk=medium] tag followed by the core mechanism in the first sentence, then the preview and one-shot constraints, then a compact Args block. Every sentence carries information; the Args section mildly duplicates the schema titles but adds origin/behavior notes.

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

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

For a 3-param mutation tool with no output schema, the description covers the mutation path, auditing, preview, and idempotency-limit. Missing are error/rollback behavior and the concrete return of a dry_run preview, but the essentials for correct invocation are present.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly does: undo_id is defined by origin, dry_run by effect, and target by pass-through behavior. The target semantics are a bit thin (which tools accept it, what values), but all three params get meaning the schema lacks.

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 ('Apply a recorded undo') and immediately explains the mechanism ('dispatching its inverse tool'), which distinguishes it from the sibling undo_list that produces the tokens. An agent can tell what this does 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?

Points to the source of the required argument ('the undoId from undo_list (or an _undo_id in a write result)'), which implicitly routes the agent through undo_list first, and describes the dry_run preview path. It stops short of explicit when-not-to-use guidance or naming alternatives, so it is clear context rather than full routing.

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

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

Annotations only supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the 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 purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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

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

With no output schema present, the description supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret 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 0% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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 recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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

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

Explicitly routes the agent: 'Use the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond that: it explains that current HostConfig limits are captured so an undo can restore them, tags the operation risk=medium, and offers dry_run previewing. It stops short of describing failure modes or permissions.

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

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

The definition is front-loaded with the [WRITE][risk=medium] tag and the core purpose before the undo rationale and Args block. Every line contributes — no filler, and the args are grouped compactly.

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

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

For a mutation tool with a nested object, no output schema, and 0% schema coverage, the description supplies the essential missing context (undo behavior, dry-run, per-parameter meaning). It is adequate; only the absence of permission/error behavior keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden and mostly succeeds: container_id is clarified as id-or-name, dry_run as preview-only, target as a config name with a default, and resources enumerates the accepted Docker update keys. The nested resources object is only partially bounded, keeping it just short of full coverage.

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

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

The description states a specific verb and resource ('Update a container's resource limits') plus a distinguishing behavioral detail ('capturing prior limits'). An agent can immediately tell this apart from siblings like restart_container, stop_container, 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?

It gives clear operational context ('Pass dry_run=True to preview') and notes target defaults, which tells the agent how to use it safely. It does not, however, state when to prefer this over alternatives such as recreate_stack for a broader change, so there are no explicit exclusions.

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