analyze_recorded_traffic

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

With no annotations provided, the description carries the full burden. It successfully discloses the return structure ('matched_fields and match_reasons') and the compact nature of summaries. However, it fails to mention operational characteristics like the scan_limit behavior, read-only safety, or filtering capabilities implied by the extensive parameter set.

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 consists of three well-structured sentences with zero waste: purpose declaration, return value specification, and workflow guidance. Information is front-loaded appropriately given the complexity of the 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?

Given the high complexity (23 filter parameters, output schema, no annotations), the description is inadequate. While it mentions the output structure, it omits any explanation of the filtering capabilities (host/path/header/body filters), which constitute the primary interaction model for this tool. The 0% schema coverage makes this omission critical.

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 has 23 parameters with 0% description coverage (titles only). The description completely fails to compensate for this gap, not mentioning any parameters, the filtering paradigm, or even the 'preset' enum which defines the analysis mode. Users have no guidance on how to construct valid queries from the description alone.

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 identifies the action ('Analyze'), resource ('saved recording snapshot'), and output format ('compact summaries'/'TrafficSummary items'). It distinguishes this tool from the sibling 'get_traffic_entry_detail' by positioning this as the summary/overview tool versus the drill-down tool.

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 provides explicit workflow guidance: 'Use get_traffic_entry_detail to drill down into a specific entry_id afterwards.' This clearly indicates the sequence of operations. However, it does not distinguish when to use this versus the similarly-named 'query_recorded_traffic' sibling.

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