Canonicalise archive (reproducible, no recompression)

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

Annotations already declare idempotentHint and destructiveHint=false, but the description adds genuinely new behavior: payloads travel bit for bit without recompression, the operation is idempotent with summary.alreadyCanonical as the signal, duplicate-name archives are refused, and corrupt/unsafe entries are preserved rather than fixed. That is exactly the kind of consequence-level disclosure annotations cannot carry.

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 core promise, then the canonical-form details, then safety caveats and verification. It is dense with em-dash clauses and list-like enumerations, but nearly every clause carries information; slightly tighter phrasing would make it scannable.

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 10-parameter mutation tool with an output schema, it covers determinism guarantees, idempotency, refusal cases and verification workflow. The one missing piece is the archive-source requirement (zipPath xor zipBase64), which the agent must infer from the schema.

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 100%, so the baseline is 3. The description restates the keepComments and keepExternalAttributes defaults, which the schema already documents, and adds only the cross-call hint that the same `date` must be passed to inspect_zip's canonicalDate — useful but marginal, and it never mentions that exactly one of zipPath/zipBase64 must be supplied.

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 — 'canonicalizeZip() rewrites a Gradle, Maven, zip, Explorer or 7-Zip archive into the canonical deterministic form' — and enumerates exactly what the canonical form is (sorted entries, one timestamp, UTF-8 flag, no data descriptor). It is clearly distinguishable from inspect_zip, verify_zip and create_zip by being a rewrite-in-place-of-bytes transform.

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 routing: 'run verify_zip first when integrity matters' and 'Verify with inspect_zip { check:['canonical-form'], canonicalDate }'. It does not explicitly say when NOT to use it (e.g. versus create_zip or modify_zip for fresh archives), so it stops just short of the top band.

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