archive_info

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

With no annotations, the description carries the full load and does so well: it declares the tool is non-extracting/non-mutating, enumerates what it inspects (encryption, nested archives reported-only, suspicious entries), and gives a downstream verdict on extractability. The disclosed limits—ZipCrypto only, AES unsupported—are exactly the kind of behavioral caveat annotations would otherwise supply. It does not explicitly state read-only permissions or cost/rate characteristics, keeping it off a 5.

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 opening two sentences front-load purpose and ordering, and the parameter notes are separated cleanly. The middle report inventory is a long run-on enumeration, but each item is information-dense rather than filler, so it stays just short of a 5.

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?

For a read-only inspection tool with three parameters, an agent has everything needed to call it correctly and anticipate the result. The one inefficiency is that it enumerates report contents at length even though an output schema exists, so some of that prose duplicates structured data rather than adding to it.

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, and it does for two of three parameters: password is scoped to ZipCrypto zips with the AES limitation, and encoding explains the legacy-name re-decode behavior, the cp437 default, and concrete codec examples. The required path parameter gets no explanation at all, and nothing says whether these options are ignored or error out on irrelevant formats—so compensation is good but incomplete.

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 and resource ('Summarize an archive without extracting anything') and immediately distinguishes itself from extraction siblings. It even names extract_archive as the downstream consumer of its verdict, so an agent can separate this from extract_archive, list_entries, or verify_archive without opening a schema.

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?

'Call this first' gives explicit workflow ordering, and 'without extracting anything' tells the agent when to prefer this over extract_archive. It stops short of excluding or contrasting the closer siblings verify_archive and list_entries, which overlap most with a summarization tool.

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