web_traffic_summary

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 read-only nature, auto-discovery behavior, time-window limitations, and conditioning on log presence. However, it does not specify what happens when no logs exist, whether the summary is returned as structured data or prose, or any resource/rate-limit impact. Adequate but not rich—no annotation 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?

Two tight sentences front-load the core function and outputs, then add the decisive differentiator, auto-discovery note, and safety flag. Every clause earns its place; 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?

Complete for a read-only analysis tool: output is described, parameter semantics are partially elaborated, and the differentiator from cloudwatch_top_ips is clear. Minor gaps—return format portrayal and behavior on log absence—are acceptable given the clear scope.

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%; schema descriptions fully document all 5 parameters. The description goes slightly beyond by mentioning auto-discovery (maps to log_path) and the hours_back limitation ('window can never reach further back than the tailed lines cover'). Baseline 3 holds—the schema carries the heavy lifting and the description adds minimal interpretive value.

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 precise verb-resource pair ('Summarize a managed instance's OWN web access logs'), enumerates the exact outputs (per-vhost request volume, req/s, status mix, top IPs/URLs), names the data source (X-Forwarded-For/mod_remoteip aware, on-box logs), and contrasts it with a sibling tool (cloudwatch_top_ips). This fully distinguishes it within a large sibling list.

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 clearly states when to use it (to see data that WAF logs cannot) and names the alternative (cloudwatch_top_ips). It implies it is the go-to for on-box log analysis but does not explicitly list exclusions (e.g., instances without direct log access, managed vs unmanaged). A dedicated when-not clause would make it perfect.

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