open_archive

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 a key behavioral trait: archives are cached, and reload=true forces re-parsing. This is valuable runtime context beyond the basic action. However, it does not specify the exact content of the 'overview' or mention any potential errors, but the caching disclosure is a significant addition.

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 short, front-loaded with the primary purpose, then adds a caching note, and ends with a concise parameter list. Every sentence contributes unique value; there is no fluff or redundancy. The structure is clean and scannable.

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 no output schema, so the description should explain what the return value includes. It says 'return an overview' but does not specify whether it provides session count, duration, capture metadata, etc. This is a notable gap. Additionally, it doesn't mention failure modes (e.g., invalid path) or how the cached data integrates with sibling tools. For a simple tool, it is mostly complete but not fully self-contained.

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 schema provides only types and titles with no descriptions (0% coverage), but the description fully compensates with a clear Args section explaining saz_path as the file path and reload as a re-read flag. This adds meaning beyond the schema and clarifies the purpose of each parameter.

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 states the tool's function: 'Parse a Fiddler .saz archive and return an overview.' This uses a specific verb ('parse') and resource ('.saz archive'), and the overview concept differentiates it from sibling tools that operate on sessions. The purpose is unambiguous and distinct from list_sessions, get_session, etc.

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 implicitly indicates this is the entry point for working with archives, as it mentions parsing and caching, while siblings operate on sessions. However, it does not explicitly state when to use this tool versus alternatives, such as 'Use this first to load an archive before filtering sessions.' The context is clear but lacks explicit exclusions or comparison.

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