Unpack a zip archive

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well: it explains that the path is resolved on the server machine, not in the caller's sandbox, and that build caches and binary entries are skipped. It does not mention permissions, rate limits, or whether anything is written to disk, but the core behaviors are covered.

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 sentences, all carrying substantive information. The main behavior is stated first, followed by the important environment safety note and the skip policy. No filler or repetition.

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 description is sufficiently complete for a moderately simple tool: it defines the operation, the environment constraint, and the filtering behavior. No output schema exists, but because the description says 'return the contents of its text files', the return concept is explained reasonably. It does not specify the output format or potential edge cases, but these are minor gaps.

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 low (33%), but the description adds critical semantics for the required 'path' parameter by emphasizing server-side resolution. The 'include' parameter already has a schema description; maxFiles only has numeric bounds, but the tool's purpose implies it limits the number of inspected files. The description partially compensates but does not fully document all parameters.

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 states a specific verb and resource: 'List a zip archive's entries and return the contents of its text files.' This is unambiguous and clearly distinguishes the tool from siblings like read_local_file by describing a zip-inspection workflow.

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 described use case—'so a project can be inspected and turned into cards'—gives clear context for when to call this tool. It does not explicitly name alternative tools or state when not to use it, but the purpose is obvious enough for an agent to choose it appropriately.

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