har_overview

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

With no annotations, the description carries the full burden and delivers two non-obvious traits: the file is streamed so 100+ MB HARs are safe, and entry numbers (#N) referenced by other tools are 0-based positions. It omits failure behavior (missing/unreadable/invalid HAR) and confirms nothing about read-only safety, though a summarizer is self-evidently non-mutating.

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?

Front-loaded with the operation and its outputs, then two short operational notes (start here, streaming safety, 0-based numbering). Every sentence adds information an agent would otherwise have to guess; 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?

An output schema exists, so the enumerated return dimensions are a bonus rather than a necessity, and the streaming/0-based numbering notes cover the highest-risk behavioral unknowns. The remaining gap is input-path semantics and error handling for an unannotated 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?

A single required `path` parameter with 0% schema description coverage; the description only implies via "The file is streamed" that this is a local filesystem path. It does not say whether the path must be absolute, whether relative paths resolve, or how the file is located, so it only partially compensates for the schema gap.

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?

States a specific verb (summarize) and resource (HAR file) and enumerates the exact aggregates produced: entry/page counts, time range, load timings, totals by resource type/domain/status class, byte comparisons, cache hits. That enumeration makes it unmistakably the overview tool rather than slowest_requests, failed_requests, or waterfall.

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?

"Start here" is explicit entry-point guidance and, combined with the sibling set, implies this is the first call before drilling into specialized tools. It stops short of naming a specific sibling or stating when-not to use it, e.g. when a single request's detail is needed instead.

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