portainer_docker_prune

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

No annotations are provided, so the description carries full responsibility for disclosing behavior. It clearly states this is a destructive action ('remove stopped containers, unused images or build cache') and explicitly warns that volumes are never pruned to prevent data loss. It also details the distinction between dangling and all images via the all_images parameter. It doesn't mention permissions or error handling, but for a prune tool, it covers the essential destructive aspects thoroughly.

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

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

The description is organized with a clear opening summary, a note about volumes, a usage hint, and an Args section. It's slightly longer than necessary but every section serves a purpose: the volume warning is critical, the disk_usage suggestion is helpful, and the args list is concise. The key information is front-loaded, making it easy to scan. A tighter wording could reduce length, but it's not padded.

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

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

Given the tool's destructive nature and three parameters, the description covers the main operational aspects: what it prunes, how targets differ, how all_images modifies behavior, and endpoint selection. It also suggests checking disk usage first. The presence of an output schema covers return-value documentation. It doesn't mention edge cases like invalid targets or partial failures, but those are less critical for an agent deciding whether to call the tool. Overall, it's complete enough for safe usage.

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 fully compensate. It does so by explaining each parameter: target with its valid values ('containers', 'images', 'build_cache'), all_images with its effect ('also remove tagged images not used by any container' and default behavior), and endpoint_id ('Target endpoint ID (uses default if omitted)'). This adds significant meaning beyond the raw types 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?

The description opens with 'Reclaim disk space: remove stopped containers, unused images or build cache', which is a specific verb+resource statement that clearly identifies the tool's purpose. It also explicitly distinguishes from portainer_volume_remove by stating volumes are never pruned, and references portainer_docker_disk_usage as a complementary tool. This makes it easy for an agent to differentiate from siblings.

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

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

The description provides explicit when-to-use guidance: 'Volumes are never pruned by this tool (that destroys data); use portainer_volume_remove for a specific volume' and 'Check portainer_docker_disk_usage first to see what is reclaimable.' It also explains the meaning of the 'target' parameter values, giving clear context for when each is appropriate. This leaves no ambiguity about when to invoke this tool versus alternatives.

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