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

Annotations already establish the tool as read-only, idempotent, and non-destructive, so the description only needs to add behavioral context beyond safety. It adds that the result includes 'a sample of known trace IDs' rather than an exhaustive list, and that stats are per-container with oldest/newest timestamps. This gives the agent an accurate model of what the call will and will not reveal, with no contradiction.

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 compact and front-loaded with the most important information: what the tool returns and its scope. The Args/Returns sections are slightly redundant with the opening sentence and the schema, but the overall structure is easy to scan and contains no filler.

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?

With one optional parameter, a clear summary of return contents, and annotations covering the read-only safety profile, the description is complete for an agent to invoke the tool correctly. There is no output schema, but the description explicitly lists the per-container stats returned, so no critical context is missing.

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 input schema already fully documents the single optional service_name parameter with an identical explanation ('Omit to get stats for all containers'). The description repeats this guidance but adds no new semantic detail beyond the schema, so the baseline 3 applies.

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 begins with a specific verb and resource: 'Return buffer statistics for one or all containers,' and then enumerates exactly what those statistics are (line counts, error/warn counts, trace IDs, timestamps). This clearly distinguishes the tool from siblings like search_logs or list_active_containers by describing an aggregated snapshot rather than a list or log search.

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 clear usage context: it is 'useful for a quick health overview before deeper investigation,' implying this is the first-look tool before using more targeted tools. It stops short of naming specific alternatives or saying when not to use it, so it earns a 4 rather than a 5.

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

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

The readOnlyHint, idempotentHint, and destructiveHint annotations already cover safety, and the description adds useful behavioral scope: only monitored Docker containers, optional Compose-project filtering, and the exact return format. It also clarifies the 12-char container ID detail, which is beyond the schema.

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 compact and front-loaded, with the purpose stated first and usage guidance at the end. The Returns section partly duplicates the earlier prose listing fields, which costs a small amount of conciseness, but the added field-name mapping and 12-char detail justify most of the repetition.

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 list tool with one optional parameter and no output schema, the description is complete: it specifies the return shape, the optional filter, the monitored-container scope, and the intended position in the workflow. An agent has enough information to call it correctly without further inference.

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 already provides 100% coverage for the single optional parameter, and the description only repeats the same filter behavior ('Filter by Docker Compose project name. Omit to list all.'). It adds no new semantic information beyond the schema, so the baseline 3 applies.

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 clearly states a specific action ('List all currently running Docker containers being monitored') and identifies the returned fields. This distinguishes it from the sibling tracing/logging tools, making its purpose unmistakable.

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 instructs to use this tool first to understand service topology before issuing other queries, which provides clear context. It does not name specific alternatives or exclusions, but the guidance is sufficient for the simple listing use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: the buffer is in-memory and the trace IDs are ordered most-recently seen first, which goes beyond what annotations provide.

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 into purpose, use-case, Args, and Returns, with no filler. The core purpose is front-loaded in the first sentence, and every line adds useful 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?

There is no output schema, so the description correctly supplies the return shape: 'a list of trace ID strings, most-recently seen first'. It also covers both optional parameters and gives a clear usage workflow, so nothing needed to invoke the tool correctly is missing.

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 100%, so both limit and service_name are already fully documented in the input schema. The description essentially repeats the schema information without adding new parameter-level meaning beyond the output ordering.

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 explicitly states 'List all trace/request IDs currently in the in-memory buffer', giving a specific verb, resource, and scope. It also frames the tool as a browsing step before investigating with search_by_trace_id, which distinguishes it from the lookup sibling.

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 gives an explicit usage condition: 'Useful when you don't already know a trace ID'. It names search_by_trace_id as the follow-up, clearly explaining where this tool fits in the investigation workflow.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining the chronological merging across all containers, the O(1) in-memory trace index, and the return of the full distributed call path. This goes well beyond the annotations and helps the agent understand expected behavior and performance.

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 with a front-loaded purpose sentence, followed by context, parameters, return value, and an example. Each section earns its place and there is no redundant filler. The information is dense but scannable.

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?

Although there is no output schema, the description explicitly explains the return value as a chronological list of log lines across all services showing the distributed call path. It also states parameter constraints, defaults, and provides an example invocation. For a two-parameter read-only tool with full schema coverage, this is complete.

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 100%, so the schema already fully documents both parameters. The Arg descriptions in the tool description largely duplicate the schema, with the only added value being a concrete example call and the embedded format examples for trace_id. Since the schema carries the semantic load, a baseline score of 3 is appropriate.

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 verb and resource: 'Return a chronologically merged timeline of all log events across every container that share a specific trace / request ID.' This clearly states what the tool does and the scope. It also positions itself as 'the primary debugging tool,' which helps distinguish it from more generic siblings like search_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 phrase 'This is the primary debugging tool' provides clear context for when to use it, and the emphasis on correlating distributed transactions signals its intended use case. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: it searches buffered lines, returns results in chronological order, and specifies the returned fields. It does not mention rate limits or buffer retention, but these are not critical for a read-only search tool.

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?

Purpose is front-loaded and the description is compact, with a useful use-case sentence and a clear return-value sentence. The Args block is somewhat redundant with the schema, but it is well organized and easy to scan.

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?

With no output schema, the description explicitly covers the return shape: chronological log lines with service name, timestamp, and level. It also covers scope, optional service restriction, level filtering, limit behavior, and the intended use case, making it sufficient for correct tool selection and invocation.

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 input schema provides 100% parameter coverage with clear descriptions, so the schema already explains every parameter and constraint. The Args section restates the same meanings without adding new semantic information, which meets the baseline but does not exceed it.

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 first sentence states a specific action (full-text search) and resource (container's buffered log lines) with an explicit optional scope. It also distinguishes itself from structured trace-ID lookup by emphasizing freeform strings, so an agent can tell it apart from search_by_trace_id.

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 use case: finding error messages, stack traces, SQL queries, or freeform strings without a structured trace ID. This implies when to prefer this tool over structured-ID search, though it does not explicitly name sibling alternatives or state exclusion conditions.

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

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

The description goes beyond the annotations (readOnlyHint=true, idempotentHint=true) by disclosing chronological ordering, the optional inclusion of WARN lines, and the error behavior when the service_name doesn't match a running container. This adds useful behavioral 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 text is organized into Args/Returns/Error Handling, but it contains the repeated corrupted token '= require(' which disrupts readability and looks like an accidental code snippet. This is a structural quality issue that prevents a higher score.

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 there is no output schema, the description does explain the return shape (N most-recent, chronological order) and error handling, which is good. Still, it lacks explicit routing to alternatives and the corrupted wording makes it less complete for an agent to confidently invoke.

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?

Input schema coverage is 100%, so the description adds little new semantic value. It provides an example value and restates the limit/warnings meaning, but does not meaningfully extend the schema descriptions.

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 specific verb ('Retrieve') and resource ('most recent ERROR and FATAL log lines from a specific container'), and gives a clear use case ('find the initial failure point'). However, the literal text contains a corrupted token '= require(' which undermines clarity, and it does not explicitly differentiate itself from the sibling tool tail_service_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 phrase 'the fastest way to find the initial failure point before diving into a full trace' implies when to use this tool, but it never names alternatives like tail_service_logs or search_logs, nor does it state when not to use it. The guidance is only implicit and contextual.

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

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

Annotations already declare this tool read-only, idempotent, and non-destructive, so the behavior bar is lower. The description adds useful behavioral detail beyond annotations: returned logs are the most recent matching lines, in chronological order, and omitting level_filter returns all levels. No contradiction with annotations was found.

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 Args and Returns and is reasonably compact. However, the first sentence contains a stray '= require(' artifact and 'return for all levels' is grammatically incomplete, which makes it less polished than it could be.

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 three-parameter read-only tool with full schema coverage and strong annotations, the description adequately covers what is returned, ordering, filtering behavior, and when to use it. The malformed opening sentence and lack of explicit error/edge-case behavior prevent a perfect score.

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 100%, so the schema already explains service_name, limit defaults and bounds, and level_filter values. The description mostly restates these details without adding new semantic information beyond what the schema provides.

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 specific action: retrieve the N most-recent log lines for a specific container or service, with optional level filtering. It also positions this tool as a way to get general context before narrowing to a trace ID, which helps differentiate it from search_by_trace_id. However, the phrase '= require(a specific container' is malformed and slightly obscures the intended meaning.

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 clear usage context by suggesting it be used to get general service context before narrowing to a trace ID. This implies when it is appropriate relative to trace-focused siblings, but it does not explicitly state when not to use it or name alternatives such as tail_service_errors or search_logs.

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