portainer_container_logs_grep

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

No annotations are provided, so the description must carry the full behavioral burden. It discloses core behavior: regex matching, case-insensitivity, tail pre-filtering, context lines, time filtering, timestamps, and endpoint selection. However, it omits edge-case behavior such as invalid regex handling, empty result behavior, permission requirements, or error conditions. For a read-only tool with no annotations, this is adequate but not thorough.

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 a lead sentence, a use-case note, and a parameter list. It is slightly verbose but each sentence earns its place. The most critical purpose and usage are front-loaded, and the parameter details are concise. No redundant information.

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 output schema exists, the description need not explain return values. All seven parameters are semantically explained, including defaults and constraints. The tool is moderately complex, and the description covers all relevant inputs and behavior. It lacks mention of potential errors or limits on pattern complexity, but for typical usage it is sufficient.

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%, and the description fully compensates by explaining every parameter in the Args section: container_id, pattern (case-insensitive), tail (lines to fetch before filtering, defaults and max), context_lines (default and max), since (formats), timestamps, and endpoint_id. It adds meaning beyond the schema's type-only definitions.

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 states a clear verb-resource pair: 'Search container logs for lines matching a regex pattern.' It differentiates itself from sibling portainer_container_logs (which presumably returns full logs) by focusing on filtered results with optional context, and explicitly notes the use case of finding errors/status codes without downloading full logs.

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 gives a clear context for use: 'Useful for finding specific errors, status codes, or keywords without downloading the full log.' It implies when to prefer this over a full-log tool, though it does not explicitly name alternatives or say when not to use. The sibling list includes portainer_container_logs and portainer_stack_logs_errors, so an agent could infer the distinction, but the description could be more explicit.

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