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.

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

With no annotations at all, the description does substantial work: it discloses defaults (zip), that symlinks are refused, that the output is never overwritten unless overwrite=true, that deterministic=true yields byte-identical output with a returned sha256, and that zips cannot be encrypted due to a standard-library limit. It stops short of stating permission requirements, error/partial-failure behavior, or where relative output paths are resolved.

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 purpose, then organized parameter by parameter with concrete defaults and examples. Dense but nearly every clause carries information; the paragraph form makes it slightly harder to scan than a bulleted list would.

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 six-parameter write tool with an output schema (so return values need no explanation) and zero annotation coverage, the description covers the risky behaviors well: symlink refusal, overwrite guard, determinism. The main remaining gap is the 'output' parameter and any error handling, which the agent would need before calling confidently.

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 supply all parameter meaning, and it does for five of six: format alternatives, sources base-name/recursive storage, excludes glob matching against stored paths and path components, overwrite protection, and deterministic semantics. Only 'output' is left unexplained (path resolution, parent directory creation, absolute vs relative).

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 ('Create an archive from files and directories') that an agent can immediately distinguish from read-only siblings such as extract_archive, list_entries and verify_archive. The following sentences reinforce the arity of the operation (sources in, single output file out).

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?

Usage context is implied rather than stated: the description tells you how to pack files but never says when to prefer this over siblings, nor any preconditions (e.g. that the destination directory must exist). It does implicitly route the agent away from this tool for reading/extraction, but only through the verb choice.

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

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

With zero annotations, the description carries the full burden and does so thoroughly: validation happens before the first byte is written, the whole call is refused atomically, mid-way failures are rolled back by removing created files, and nested archives are not extracted. It also enumerates exactly what triggers refusal (traversal, absolute/drive-letter paths, backslash tricks, out-of-bounds symlinks, hardlinks, device/FIFO, duplicate names, zip bombs) and notes that the max_* knobs can only tighten server limits, never loosen them.

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?

Purpose is front-loaded in the first clause, then safety guarantees, then selection, then write-mode behavior, then limits — a logical progression with no repeated content. Despite its length, every sentence carries distinct, decision-relevant information.

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 high-risk filesystem mutation tool with 11 parameters and no annotations, the description covers atomicity, rollback, overwrite policy, symlink policy, limit semantics and refusal conditions. An output schema exists, so return values need not be described, and nothing else an agent needs to call this safely is missing.

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 coverage is 0% with 11 params, so the description must compensate and largely does: members accepts names, directory prefixes and globs; symlinks explains the 'skip' default versus 'create' and its Windows privilege caveat; max_total_mb/max_ratio/max_entries are framed as limit-tightening only; overwrite and dry_run defaults are stated outright. However 'password' and 'encoding' are never mentioned at all, leaving two non-obvious parameters undocumented in both schema and prose.

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?

Opens with a specific verb, resource and scope: 'Safely extract an archive (all of it, or selected members) into dest.' The extraction verb is unmistakable against siblings like create_archive, verify_archive, list_entries and read_entry, so an agent can route on name plus first line alone.

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?

Gives concrete when-to-use guidance for the key switches: 'members' is for salvaging safe entries from a refused archive, 'dry_run=true validates and lists what would be written', 'overwrite' governs clobbering. It never names the sibling tools (e.g. verify_archive first, or list_entries to discover member names), so alternates are left implicit rather than explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the default line format (kind, size, mtime, name), the '!!' refusal marker, and that truncation past the limit is summarized as a count rather than silently dropped. It omits any mention of password-protected archives or encoding handling, which the presence of password/encoding parameters implies is relevant.

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 core purpose is front-loaded in four words, then per-parameter behavior follows in compact parenthetical lines. Every sentence adds information; nothing is redundant.

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 return values need no further explanation and the description correctly focuses on parameters and the '!!' marker. The missing discussion of encryption/password and encoding is the only notable gap for a six-parameter 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 and it does so for half the parameters: glob semantics (full path vs. filename, with '*.py' and 'src/*' examples), tree rendering, and limit's default of 200 with truncation behavior. The required path, encoding, and especially password are left entirely undocumented, so a meaningful compensation gap remains.

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 opening sentence pairs a specific verb and resource ('List archive members') with an explicit scope boundary ('without extracting'), which cleanly separates it from extract_archive and read_entry. An agent can select this tool without inspecting the 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?

'without extracting' and the note that '!!' marks entries extract_archive would refuse implicitly route the agent to extract_archive when content is wanted. It stops short of an explicit when-to-use/when-not statement naming alternatives (search_in_archive, archive_info), so it is clear but not fully prescriptive.

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

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

With no annotations, the description does real work: it discloses the return format (UTF-8 text vs hex dump of first 512 bytes), the default and hard byte caps, and the truncation header. However, it never says this is a read-only operation, and it is silent on the password parameter — a critical omission for encrypted archives.

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 scope constraint is front-loaded in the first sentence, and the following sentences cover output format and limits without padding. Slightly dense with parenthetical detail, but every clause carries information.

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 return-format sentence is partly redundant, but the truncation and byte-cap behavior is genuinely useful. The gaps are meaningful: nothing explains how encrypted archives or the encoding override are handled, which an agent needs before invoking.

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 coverage is 0% across 5 parameters, so the description must carry the load. It explains max_bytes (default 64 KiB, hard cap 1 MiB) and member well, but path, encoding, and password are left completely undefined in both schema and description — three of five parameters undocumented.

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 ('Preview ONE member') plus the key differentiator: it does not extract the rest of the archive. This cleanly separates it from extract_archive and from list_entries, which is explicitly named as the source of member names.

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?

Implies the workflow (call list_entries first to get the exact member name) and implies the alternative is full extraction, but never states when to prefer this over search_in_archive or extract_archive, and gives no exclusions or error guidance for a wrong member name.

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

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

With no annotations supplied, the description carries real weight: it discloses that binary members are skipped and counted, the per-member 5 MiB and 64 MiB total read caps, and that the result reports when a cap was hit. It does not say how encrypted members behave when 'password' is omitted, nor whether a non-archive path raises an error, which are the remaining behavioral gaps.

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 core purpose is front-loaded in one short sentence, and the following sentences are each additive detail rather than filler. The cap sentence is slightly convoluted ('each member is read at most 5 MiB and the whole search at most 64 MiB') but still parses cleanly.

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, yet the description still gives the line format 'member/name:LINE: text' and the cap-notification signal, which is helpful surplus. For a 7-param search tool with no annotations, the main omission is any guidance on 'password' and 'encoding', which an agent would otherwise have to infer from parameter names.

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% across 7 parameters, so the description must compensate. It adds genuine meaning for 'pattern' (Python regex, per-line matching) and 'glob' (member selection), but says nothing about 'encoding', 'password', 'ignore_case', or 'max_matches', leaving four parameters undocumented anywhere.

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?

First sentence gives a concrete verb ('grep') and resource ('text members inside an archive') plus a defining constraint ('without extracting it'). That constraint alone distinguishes it from extract_archive and read_entry among the siblings.

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 phrase 'without extracting it' implicitly routes the agent away from extract_archive for content search, and 'glob narrows which members are searched' hints at scoping before reading. It stops short of naming an explicit alternative or exclusion, so it is clear context rather than full when/when-not guidance.

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

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

No annotations exist, so the description carries the full burden, and it does well: 'Writes nothing' rules out mutation, the return convention ('OK ...' vs 'FAILED ...' with bad members) is disclosed, and the encrypted-member caveat is called out. It omits cost implications — decompressing every file could be slow on large archives — and does not say whether partial results are returned on failure.

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?

Three short sentences, zero filler, with the core operation front-loaded and the behavioral caveats trailing. Every sentence carries distinct information.

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 return formatting need not be exhaustive, and the description still summarizes it usefully. For a zero-annotation, 3-parameter tool the main residual gap is the unexplained encoding parameter and the lack of any performance caveat for large archives.

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 coverage is 0%, so the description must supply parameter meaning, and it explains only the password parameter's effect on encrypted members. The 'encoding' parameter is completely undocumented in both schema and description, and 'path' is left to inference.

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 — 'Test archive integrity by decompressing every file and checking CRCs/checksums' — which clearly separates it from siblings like extract_archive, list_entries, and archive_info. An agent can tell this is a validation operation, not a read or extraction.

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?

No explicit statement of when to prefer this over extract_archive or archive_info, nor any preconditions such as checking corruption before extraction. The encrypted-member condition on the password parameter is the only conditional guidance, and it is about one parameter rather than tool selection.

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