Server Quality Checklist

Tool Scores

• describe_engineA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that: 'network is always \'none\'' discloses connectivity behavior, 'Offline preflight (no archive needed)' clarifies it never touches archives, and it discloses that certain engine exports are deliberately not exposed (with why). No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The key differentiator ('Offline preflight (no archive needed)') is front-loaded, and the usage guidance is placed at the end, but the body is a single long run-on enumeration that is dense and hard to parse quickly. For a capability-discovery tool the enumeration is genuinely useful, but it would benefit from structuring the list of returned items.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With an output schema present, return-value explanation is already handled structurally. The description covers an unusually complete scope for a capability tool: versions, deflate tiers, runtime codecs, worker threads, registry, limits, operator ceilings, server caps, sandbox/cache state, error/diagnostic codes, and unexposed exports — plus the 'network is always none' note. Nothing an agent needs to interpret capabilities or refusals is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, with both 'fields' (dot-path projection with _meta.unmatchedFields reporting) and 'verbosity' (full/summary enum) already well-documented in the schema. The description adds no parameter-specific detail beyond the schema, so the baseline 3 applies — the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource ('Offline preflight') and enumerates a precise, concrete set of what it returns (versions, deflate tier, codecs, limits, ceilings, error codes, unexposed exports). The 'no archive needed' note and the phrase 'server / engine capabilities' clearly separate it from sibling zip-manipulation tools that operate on archives.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The closing guidance 'Call it first in a session, or whenever a cap / ceiling refusal needs interpreting' is explicit when-to-use advice. It does not explicitly name alternatives or when-not-to-use, but the 'no archive needed' framing implies differentiation from the archive-dependent siblings, giving clear context without formal exclusions.

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

• modify_zipA
  4.3/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses rich behavioral details: append mode leaves removed/replaced payloads in the file (data remanence), triggers a ZIP_DEAD_BYTES_RATIO diagnostic past 50% dead bytes, and notes 7-Zip reads stale payload. It also specifies that no edits with an unchanged comment return the same bytes (summary.noOp), and that duplicate entry names are refused. These are critical behavioral traits not inferable from annotations alone.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and well-structured: it front-loads the purpose, then explains the two modes with their consequences, mentions the no-op and duplicate-name cases, and ends with output options. Every sentence adds information without redundancy, though the title already implies 'incremental, no recompression', so the first sentence repeats that concept slightly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (11 parameters, nested operation objects, multiple modes), the description covers the essential decision points: when to use append vs compact, the duplicate-name restriction and its alternative, and the output modes. The extensive input schema and output schema handle parameter-level details, so the description does not need to repeat them. It could mention the 'strict' or 'limits' parameters, but those are self-explanatory in the schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 text does not add parameter-specific meaning beyond what the schema already provides; for instance, the mode parameter's behavior is already fully described in the schema's mode field. The description's main value lies in overall behavioral context rather than parameter semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'Edit an existing archive without recompressing anything' and enumerates the exact operations (add / replace / remove / rename / setComment), making the tool's purpose specific and unambiguous. It explicitly differentiates from create_zip by stating 'prefer create_zip for a full rebuild' and notes that duplicate entry names are refused, so an agent can immediately tell this tool apart from its siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear usage context: it contrasts the 'append' and 'compact' modes, explaining the trade-offs (byte preservation vs. true removal) and the data remanence caveat. It explicitly names create_zip as the alternative for full rebuilds or duplicate-name sources. However, it does not exhaustively list all alternative tools (e.g., extract+modify+recreate), leaving some inference to the agent.

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

• sanitize_entry_pathsA
  4.3/5.0
  Behavior4/5

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

  The description explains the transformation and the null cases (empty, NUL byte, absolute, etc.), which clarifies the tool's behavior. The readOnlyHint, idempotentHint, and destructiveHint annotations already indicate no side effects, and the description does not contradict them. It adds value by detailing the return format and failure modes.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise yet information-dense. It packs the core behavior, the return format, the list of invalid patterns, and usage guidance into two sentences without redundancy or unnecessary detail. It is well-structured and front-loaded with the main action.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given that an output schema exists (not shown), the description still provides essential context about the return values (safe path or null with rule) and the tool's role in extraction workflows. It covers the main use case, the nature of the operation, and the absence of archive dependency. No critical information is missing for an agent to decide when and how to call it.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema provides descriptions for all three parameters—names, fields, and verbosity—covering 100% of them. The description does not substantially add meaning beyond the schema for parameters; it mostly reiterates the names parameter's purpose and the output format. Therefore, baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool applies a sanitization function to a list of entry names, returning safe relative paths or null with the specific rule that fired. It also names the exact function (sanitizeEntryPath) and explicitly says it is for extraction or external filesystem sinks, distinguishing it from sibling tools like extract_zip or read_zip_entry.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit guidance on when to use the tool ('Use it when you extract with another tool or plan an external filesystem sink') and notes that no archive is needed. It could be slightly more explicit about when not to use it (e.g., when you only need to inspect paths without sanitization), but the provided context is sufficient.

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

• compute_crc32A
  4.4/5.0
  Behavior5/5

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

  Annotations already indicate read-only, idempotent, non-destructive behavior; the description adds valuable behavioral detail such as streaming in 1 MiB chunks, continuation via seed, and comparison via expect that produces matches. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and front-loaded with the main function, but it repeats seed/expect behavior also present in the schema and includes an optional implementation detail (slice-by-8) that adds little operational value. Still well-structured and appropriately brief.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers algorithm, input forms, chunking, stream limits, and cross-check use case, but the schema has no required fields and the description never states that exactly one of text, dataBase64, or sourcePath must be provided. This is a meaningful gap for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema descriptions already cover all five parameters with exclusivity and size constraints, so the bar for additional meaning is high. The prose adds context by explaining seed as chunk continuation and expect as a compare-with-known-value, but most parameter semantics are already present in the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States the tool computes the IEEE 802.3 CRC-32 checksum of inline bytes/text or a sandbox file, with a concrete use case for cross-checking list_zip_entries data against a disk file. The title reinforces the action, and the algorithm/resource scope are unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides an explicit use case ('Use it to cross-check an entry's crc32 from list_zip_entries against a file on disk') and describes how to chain chunks with seed and assert with expect. It does not name alternative tools or explicitly say when not to use it, so it falls just short of full guidance.

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

• create_zipA
  4.4/5.0
  Behavior5/5

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

  This is a remarkably transparent description. It discloses default reproducibility semantics (canonical order, DOS-epoch timestamps), how to opt out (defaultDate:'now'), the exact meaning of summary.deterministic (true only with compression.deterministic:true), the behavior of Zip64 (emitted on overflow), output mode constraints (≤50 MiB base64, streamed file never overwritten), and conformance to ISO/IEC 21320-1. Annotations provide idempotentHint=true, and the description adds nuance that idempotency is runtime-specific unless deterministic:true is set — not a contradiction but a valuable clarification. It far exceeds the annotation coverage.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness2/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single dense paragraph with many clauses separated by semicolons and parentheses. While every sentence adds information, it is not front-loaded and is far longer than needed. The title already conveys the determinism point, yet the description repeats it. For a tool with 12 parameters and a rich schema, some verbosity is justified, but this reads more like a spec dump than a concise guide. It would benefit from bullet points or a breakdown by concern.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool of this complexity (12 parameters, nested objects, multiple output modes, determinism controls, security limits), the description is exceptionally complete. It covers output formats and limits, sandbox behavior, worker parallelism, diagnostics (ZIP_TIMESTAMP_NOT_PINNED, ZIP_STRICT_DIAGNOSTIC), Zip64 conditions, and conformance validation. The output schema exists and the description complements it without redundancy. Nothing an agent needs to invoke this correctly is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has 100% description coverage with detailed explanations for every parameter, so the baseline is 3. The description adds value beyond the schema by explaining cross-cutting behavior: how order relates to EPUB/JAR, when Zip64 triggers, the meaning of summary.deterministic, and the worker-pool byte-identity guarantee. It doesn't simply repeat parameter docs but gives operational context, justifying a 4.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a clear verb and resource: 'Write a ZIP from inline entries...' It lists the content sources (dataBase64, text, sourcePath, directory) and distinguishes itself from the sibling tools by being the only creation tool in a list dominated by inspection, extraction, and modification. The title also clarifies reproducibility, making the tool's core purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states what the tool does and covers when to use it, but it does not name alternatives or exclude scenarios. It mentions that 'parallel' is 'only worth it for many large entries' and that 'stream:true' is for bounded memory, which gives usage hints. However, it doesn't say 'use this instead of X' — that is left implicit given the sibling list. The lack of explicit exclusions keeps it from a 5.

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

• verify_zipA
  4.5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail beyond that: it never throws for archive problems, error placement, skipped vs failed entry semantics, the isError-only-for-caller-mistakes rule, and the effect of entries:'failed' and verbosity:'summary'. This fully discloses the tool's safety and edge-case behavior.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but every sentence adds operational value: core purpose, failure semantics, entry-status nuance, and a usage directive. It is front-loaded with the main verdict. A little longer than strictly necessary, but no filler—the tradeoff between length and completeness is well balanced.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 7-parameter tool with nested objects, enums, and an output schema, the description covers the essential behavioral contract: when it fails, how to interpret results, and how to keep output frugal. The presence of an output schema relieves the description from detailing return fields. Minor gaps remain (e.g., no explicit mention of default verbosity vs summary), but these are inferable from the schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% (all 7 parameters have descriptions). The description adds value by explaining the interaction between entries and verbosity, the security implications of raising limits, and the exclusive relationship between zipPath and zipBase64. It also frames the output semantics (failed vs skipped) that affect parameter choice. Slightly above baseline because it contextualizes parameters beyond their literal schemas.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific verb (verify), resource (archive integrity), and scope (eager structural validation plus per-entry CRC-32/size/local-header agreement). It also defines the success criterion (`ok` true) and distinguishes from extraction by naming extract_zip, so an agent can tell it apart from siblings without opening schemas.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit when-to-use guidance: 'run it on any archive from an untrusted source before extract_zip.' It also clarifies the tool never fails for archive problems, so it is safe for untrusted input. However, it does not name alternatives like scan_zip_forward or list_zip_entries for non-verification needs, leaving some routing to inference.

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

• inspect_zipA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral detail: eager vs. lazy validation, refusal with ZIP_* codes, escalation via strict, and the fact that certain checks are deferred to verify_zip. It even discloses that hostile shapes are refused here. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single dense paragraph but well-organized: purpose first, then outputs, then behavior, then CI/usage, then input. Every sentence contributes new information without fluff. While not short, it is appropriately detailed for a complex tool with 9 parameters and nested objects. The front-loading of the core purpose aids quick comprehension.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool of this complexity, the description covers essential aspects: the eager validation behavior, the check/assert mechanism, the token-frugal modes, input options (base64 vs path), strict escalation, and security limits. Since an output schema exists, the description need not detail return structure, but it does mention checks[] and checksPassed. Nothing critical for an agent to call it correctly is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaningful context for key parameters: check/assert as a CI gate, verbosity/fields for token frugality, and validate's eager default. It does not repeat schema details but explains their purpose, which adds value beyond the structured fields.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Read-only archive report in ONE call' followed by a detailed enumeration of outputs (size, counts, Zip64, determinism verdict, diagnostics). It explicitly distinguishes from verify_zip by stating which divergences are NOT caught here. This makes the tool's purpose unambiguous and differentiated from siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context on when to use the tool (for a comprehensive read-only report and CI gating via check/assert) and explicitly notes that method/CRC/size divergences are handled by verify_zip. It also mentions the create/modify → verify/extract chain, implying usage in that flow. However, it doesn't explicitly say 'use this instead of X when...' for all alternatives, but the main alternative (verify_zip) is covered.

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

• draft_governance_issueA
  4.8/5.0
  Behavior5/5

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

  The description adds substantial behavioral detail beyond the annotations: it states the tool never writes to GitHub or the network, enforces compliance policy with a GOVERNANCE_VIOLATION exception, and explains outputMode behavior. This is richer than the annotations alone and does not contradict them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but densely packed with essential information, front-loading the core purpose and constraints. It could be tightened slightly, but every sentence serves a purpose (compliance rules, targetRepo mapping, output modes, usage guidance).

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (11 parameters, nested objects, compliance checks) and that an output schema exists, the description covers all critical aspects: HITL behavior, policy enforcement, targetRepo selection, output modes, and required duplicate search. Nothing an agent needs to invoke it correctly is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description adds value by explaining targetRepo semantics (engine vs wrapper), requiring duplicateSearchPerformed to be true, and clarifying reproduction constraints. This elevates it above baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Produce a LOCAL GitHub issue draft + compliance report') and resource (zipnative / zipnative-mcp), and clearly distinguishes its purpose from siblings like describe_engine. It also notes the 'NEVER submit it' HITL contract, making the tool's scope unmistakable.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly instructs when to use the tool ('Use it only after reproducing a defect') and when not to ('for questions read describe_engine / AGENTS.md instead'). It also mentions the human-in-the-loop contract, giving clear context on the appropriate workflow.

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

• read_zip_entryA
  4.8/5.0
  Behavior5/5

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

  Discloses duplicate-name behavior, range CRC non-verification, raw payload semantics, strict diagnostics, limit overrides, and exclusive zipPath/zipBase64 handling. This goes well beyond the readOnly/idempotent annotations and matches them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the core action and selection, then uses compact semicolon-separated clauses for modes and constraints. Despite density, there is no filler or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the output schema is present and all 12 parameters are covered, the description supplies the operational context needed to call the tool correctly, including failure modes and security bounds.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Every parameter is described with added nuance: exclusive relationships, byte offsets, encoding fallbacks, default limits, operator ceilings, and sandbox constraints. The schema coverage is 100% and the prose meaningfully supplements it.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description opens with 'Read ONE entry without extracting the archive', clearly naming the verb, resource, and selection by name or index. It distinguishes this from listing/extracting via mode descriptions and the one-entry focus.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Describes when to use data/raw/verify, range windows, and zipPath for create/modify → verify/extract chains. It does not explicitly contrast with list_zip_entries for multiple entries, but the one-entry scope and mode guidance are sufficient.

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

• inflate_rawA
  4.9/5.0
  Behavior5/5

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

  The description discloses important runtime behavior: decompression stops past the bound with ZIP_INFLATE_OUTPUT_OVERFLOW, trailing bytes are reported as leftover, unsupported codecs raise ZIP_UNSUPPORTED_METHOD, and file outputs never overwrite. These details go beyond the annotations and accurately portray side effects and limits.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense and information-rich but somewhat repetitive with repeated mentions of boundedness, output caps, and related error modes. It is still well structured and each clause contributes useful guidance, so it remains concise enough for practical use.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity, the description fully covers the required inputs, constraints, output mode choices, error conditions, and safe usage boundaries. It also provides enough context for an agent to decide when to use this tool versus read_zip_entry, making it complete in context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already covers all parameters, and the description adds meaningful semantics such as exclusivity between dataBase64 and sourcePath, the meaning of numeric method IDs, inline vs file output caps, and streamed file writes. This exceeds the baseline expected for fully covered schemas.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the operation as decompressing a raw DEFLATE (RFC 1951) stream, including the payload source such as read_zip_entry mode:'raw'. It is specific about the resource and action, and the title aligns with the described behavior.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use the tool ('only for a raw payload or a bare deflate stream') and when to prefer an alternative ('to read an entry's content prefer read_zip_entry mode:"data"'). It also explains mandatory bounds, output modes, and codec selection, leaving little ambiguity.

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

• list_zip_entriesA
  4.9/5.0
  Behavior5/5

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

  The description openly states the operation is read-only and does not decompress anything, matching readOnlyHint, idempotentHint, and destructiveHint annotations. It also discloses output details like the sanitized path and unsafe-name null behavior, with no hidden side effects.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense yet well structured, with no filler or redundant phrases. The long field enumeration is purposeful for an inventory tool, and the two-sentence format front-loads the most important behavior (read-only, no decompression) before listing details.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the rich schema, annotations, and output schema, the description is complete: it covers purpose, output shape, filtering, paging, verbosity, and sibling tool differentiation. It does not need to repeat schema details, and no essential context is missing for an agent to call the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema provides thorough descriptions for all 11 parameters, and the description adds behavioral meaning by explaining output row contents, filter modes, paging, and verbosity/fields projection. A small deduction is warranted because a few parameters such as strict, validate, and limits are only covered in the schema, though the schema is explicit.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb and resource: 'Read-only central-directory inventory' with 'every entry ... in directory order as a full row' and lists the exact fields. It clearly distinguishes this tool from siblings by saying it does not decompress anything and by naming inspect_zip, read_zip_entry, and extract_zip as alternatives.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says when to use this tool versus alternatives: 'Prefer inspect_zip for a one-shot summary and read_zip_entry / extract_zip for content.' It also gives concrete usage semantics for filter, offset/limit, hasMore, and verbosity, so an agent knows exactly how to page and select entries.

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

• scan_zip_forwardA
  4.9/5.0
  Behavior5/5

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

  Transparently discloses non-authoritative behavior ('result is NOT authoritative'), the risk of hostile archives, and concrete behaviors like tolerateTruncation returning partial inventory and strict mode escalating diagnostics. No contradiction with the readOnly/idempotent annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense and well-structured, front-loading the core purpose and caveats before parameter details. It is slightly verbose but every sentence carries necessary qualification for a security-sensitive tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers the primary use case, limitations, security bounds, and relationship to sibling tools. It also references output fields like stoppedAt and sanitizedPath, making the behavior understandable without needing to inspect the output schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Although the schema already has 100% coverage, the description adds valuable semantic context, such as explaining data modes ('none' skips payloads, 'verify' decompresses for CRC checks, 'include' returns base64) and that tolerateTruncation yields a partial inventory.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific verb ('Walk') and resource ('LOCAL headers') in stream order, and explicitly identifies itself as a central-directory-less reader. It clearly distinguishes from sibling tools like inspect_zip and list_zip_entries.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit when-to-use guidance: 'The only tool that works on a truncated archive or a stream cut mid-way' and 'Prefer those tools whenever the whole archive is available; use this one for forensics.' This leaves no ambiguity about the intended context.

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

• extract_zipA
  5/5.0
  Behavior5/5

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

  Details behaviors: never overwrites, skips unsafe paths when disabled, dry run behavior, eager opening and refusal, and never materialises symlinks—transparent about side effects beyond the boolean hints.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Long but dense; every sentence carries information, front-loaded with the core extraction behavior and security defaults, and ends with a practical recommendation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers security guards, options, output modes, dry run, and error cases; the output schema exists, so return values are documented elsewhere; nothing essential is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Every parameter has a schema description; the tool description adds default values, interactions (e.g. ANDing of filter criteria), and security ceiling explanations, fully covering semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states it extracts a zip archive, with a strong security posture, and distinguishes from read_zip_entry for single-file use.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Names read_zip_entry as the preferred alternative for single files, and mentions the create/modify → verify/extract chain, giving explicit usage context.

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