compose_down

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

Beyond the destructiveHint annotation, the description discloses meaningful behaviors: images are kept, named volumes are only removed with volumes=True, non-zero CLI exits do not raise, and missing plugin/timeout conditions still raise. It also tells the agent to inspect returncode/stderr, which is valuable runtime context.

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 well-organized and front-loaded: a one-sentence purpose, a short behavioral note, then structured Args and Returns sections. Every sentence adds information without unnecessary padding.

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 compose operation with no output schema, the description provides the return dict shape, subprocess error semantics, and parameter meanings. The only notable gap is the undocumented 'profiles' parameter, which prevents it from being fully complete for all 7 inputs.

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 of explaining parameters. It explains six of seven parameters with useful detail (project_dir default/copy behavior, repeatable -f files, volumes destructive flag, timeout default). However, the 'profiles' parameter in the schema is not mentioned at all, leaving one parameter undocumented.

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

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

The description opens with a specific action and resource: 'Stop and remove containers, networks (and optionally volumes) for a compose project.' It also explicitly names itself as the inverse of compose_up, which clearly differentiates it from compose_stop and other compose-related 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?

It explicitly contrasts with compose_stop ('Use compose_stop to stop without removing anything') and states when the destructive volume removal applies (volumes=True). This gives an agent clear routing guidance among related compose lifecycle tools.

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