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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description wisely spends its words elsewhere: it discloses default scoping to sourceInstanceId so replicas aren't interleaved, the strict-before/strict-after semantics, chronological sort order, and the queryStats payload. This is meaningful behavior beyond the annotations.

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?

Front-loaded one-line purpose, then defaults and return shape under clear labels. Every section carries information, though the Defaults block partially duplicates schema content and the formatting is somewhat sprawling for a 4-parameter tool.

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 takes on the burden of describing the return shape (anchor, before, after, queryStats) and it does so completely, including sort order. An agent has everything needed to call and interpret this tool.

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%, so the baseline is 3; the description restates the same before/after/sameSource defaults the schema already gives, which is redundant. It earns the extra point by explaining why sameSource defaults to true (same pod/process, avoiding interleaved replicas) — conceptual meaning the schema does not convey.

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?

States a specific verb+resource+scope: return logs chronologically around a given logId, with the anchor included. The framing as 'neighbour' queries clearly distinguishes it from get_log and logs, which fetch a single log or a stream rather than a window around an anchor.

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?

Names the concrete question it answers ('what happened right before/after this alert?') and explains the sameSource=false alternative for cross-pod queries with an example. It stops short of explicitly contrasting with named siblings like get_log or logs, so it isn't a full when/when-not routing statement.

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