docker_images

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes beyond them by stating the approval gate and the HOMELAB_DOCKER_ALLOW_WRITES=true escape hatch, plus what each destructive action actually destroys. It does not mention the dry_run flag or whether force changes deletion semantics, so some behavioral surface is uncovered.

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

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

Two sentences, no filler, with the read-only versus write distinction front-loaded before the per-action semantics. The only inefficiency is the one-word 'Images.' opener, which conveys little on its own.

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

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

An output schema exists, so return values need not be described. However, for a seven-parameter, multi-action destructive tool with no schema descriptions, the description leaves the pagination and force parameters and the dry_run safety valve undocumented, which is a meaningful gap.

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

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

Schema description coverage is 0%, so the description carries full burden for seven parameters. It only glosses the action values and implicitly image/tag; force, limit, offset, and especially dry_run (a safety-relevant flag) go entirely unexplained in both schema and description.

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

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

The description names the resource (Docker images) and enumerates the four actions in the enum (list, pull, remove, prune), which makes the tool's scope understandable. The opening fragment 'Images.' is terse and the verb is only implied by the action list, but an agent can still tell this is image management rather than container management.

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 clearly separates the safe read path (list) from the mutating paths (pull, remove, prune) and explains the difference between remove and prune, which is exactly the selection decision an agent needs. It does not say when to prefer docker_inventory or docker_containers over this tool, so sibling routing is left to inference.

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