container_logs

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: default snapshot behavior, follow mode termination conditions (limit_lines, timeout_seconds, container exit), the SSH stream cancellation limitation, and the return type. This exceeds what annotations provide, though it doesn't mention potential output size or more detailed pagination.

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-structured with an opening summary, a caveat paragraph, and an arg list. It is somewhat long (about 180 words) but all content is relevant and front-loaded. The arg list is necessary because the schema lacks descriptions, and the caveat is critical for safe operation.

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 10-parameter tool with two modes, the description covers all parameters, mode semantics, a platform-specific caveat, and the return type. The output schema exists, so return format details are not needed. The description is complete enough for an agent to invoke the tool correctly in various scenarios.

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%, but the description fully compensates with a comprehensive 'args' list that explains every parameter, including mode-specific applicability (until in snapshot mode; limit_lines/timeout_seconds in follow mode). This is excellent parameter documentation that goes well 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?

Description uses a specific verb ('Get') and clearly identifies the resource ('logs of a container'), while elaborating on two modes: snapshot and bounded live tail. It distinguishes itself from sibling log tools (service_logs, compose_logs) by naming the container as the scope and detailing the modes, making the purpose unambiguous.

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 guidance on when to use follow mode vs snapshot mode, and even gives a concrete caveat for ssh:// daemons where follow mode cannot be canceled, recommending snapshot mode for hard time bounds. This is strong when/when-not guidance, though it doesn't compare to alternative log tools explicitly.

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