extract_archive

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.