analyze_blocked_traffic

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

Annotations already establish read-only and non-destructive behavior. The description adds valuable context: firewall logs are raw text and IPs are extracted via pattern matching, alerting the agent to potential data quality issues. Most importantly, it discloses a known upstream bug causing server-side OOM on large log files and suggests a fallback. This goes well beyond the annotations and provides actionable risk mitigation.

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 clear front-loaded first sentence. The first paragraph concisely explains the tool's purpose and output fields, and the second paragraph delivers a critical warning in a clearly separated block. Every sentence serves a specific purpose, and the length is appropriate for the tool's complexity.

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 presence of an output schema and annotations, the description covers the tool's behavior thoroughly: what it does, how it processes data, known limitations, and a fallback. It doesn't explain the full return structure, but that is handled by the output schema. For a read-only analysis tool, this level of completeness is sufficient for an agent to invoke it safely and know what to expect.

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 provides 100% coverage for both parameters: limit has a description with max 50, and group_by_source has a description with threat scoring. The description does not add parameter-specific details beyond what the schema states; it mentions grouping in general but doesn't clarify the boolean behavior or output differences. With high schema coverage, the baseline 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: 'Analyze blocked traffic patterns from firewall logs.' It then details the exact behavior—retrieves recent blocked log entries, groups by source IP, shows hit counts, destination IPs, and a threat score. This clearly distinguishes it from siblings like get_firewall_log (raw logs) and diagnose_blocked_traffic (higher-level diagnostic).

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 clearly implies when to use it: when analyzing aggregated blocked traffic patterns rather than viewing raw logs. It provides a fallback in case of failure (SSH/web UI), but it does not explicitly name alternative tools or state when not to use it. Given the presence of sibling tools like get_firewall_log and search_logs_by_ip, being more explicit would earn a 5, but the context is clear enough for an agent to select correctly.

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