get_packet_by_number

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

With no annotations provided, the description carries the full burden. It discloses that the tool fully decodes the packet, that frame numbers are one-based, and that an absent frame returns found=false instead of raising an error. It also lists the return fields. This is solid behavioral disclosure, though it doesn't mention performance implications or whether the capture must be loaded (though capture_id implies it).

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 and efficient: a one-sentence purpose, a clarifying alias note, a behavior note, and a compact Args/Returns section. Every sentence earns its place, and the key differentiator (alias of dissect_packet) is front-loaded.

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?

The tool has an output schema, so return values are already structured. The description adds the found=false behavior, one-based numbering, and the alias relationship, which are the key contextual details an agent needs. It doesn't mention prerequisites like 'capture must be loaded', but the capture_id parameter and sibling load_capture make that inferable. Overall, quite complete for a lookup 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 description coverage is 0%, so the description must compensate. It does: it explains capture_id is 'ID of a currently loaded capture' and packet_number is a 'Positive frame.number value'. This adds meaning beyond the bare schema types (string/integer). It could go further by noting the range or format of capture_id, but it covers the essentials.

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 fully decode') and resource ('one packet by its Wireshark frame number'), and explicitly distinguishes itself as a 'lookup-oriented alias of dissect_packet'. This makes the tool's purpose unambiguous and differentiates it from the sibling dissect_packet.

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 indicates this is a lookup-oriented alias of dissect_packet, implying when to use it (direct frame-number lookup) versus the alternative. It also explains the absent-frame behavior (returns found=false instead of raising an error), which is useful usage context. However, it doesn't explicitly state when NOT to use it or name other alternatives like get_packets_between_frames.

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