List containers

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

No annotations are provided, so the description carries the burden. It discloses the default filtering behavior of showing only running containers and the option to include stopped ones. This is adequate for a read-only tool, but no further behavioral traits (e.g., rate limits, auth) are mentioned.

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

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

The description is two sentences long, front-loaded with the core purpose. The second sentence adds value by explaining default behavior and parameter usage. No wasted words, though slightly more detail could be added without harming conciseness.

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

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

For a simple tool with one optional boolean parameter and no output schema, the description covers the key aspects: what the tool does, what columns are shown, default filtering, and the parameter. It provides sufficient context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, providing a baseline of 3. The description mentions the `all` parameter and its effect (include stopped containers), which aligns with the schema description. No additional semantic context beyond the schema is added.

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

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

The description specifies the verb 'List' and the resource 'Docker containers', lists the displayed columns (status, image, ports, uptime), and distinguishes itself from siblings by positioning as the best starting point for understanding deployments.

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 states it is the best starting point to understand what is deployed, implying primary usage for overview. It mentions the default behavior (only running containers) and when to use the `all` parameter, but does not explicitly exclude alternative tools like container_logs or inspect_container.

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