McpStamp Zip Archives

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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 description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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 single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.

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?

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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 uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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 description provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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?

Two dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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?

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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?

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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 description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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?

The description goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing two meaningful behaviors: a name clash is refused unless replace, and an archive holding unsafe entries is refused rather than rewritten. These are concrete, actionable details. It does not contradict the annotation hints.

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 description is exactly two sentences, front-loading the primary action and then stating the key behavioral caveats. There is no filler or redundant restatement of the title.

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?

Given full schema coverage, absence of an output schema, and a moderate parameter count, the description captures the core use, the file-placement modes, and the two important refusal behaviors. An agent can decide when to call and what to expect on basic conflicts, though it stops short of explaining success return values or what 'unsafe entries' means exactly.

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?

The input schema fully describes all 6 parameters, so the baseline is 3. The description reinforces the meaning of paths and prefix ('under their own names, or under prefix') and the replace rule ('name clash is refused unless replace'), but it adds no parameter-level detail beyond what the schema already provides.

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 names a specific verb and resource: add files to an existing archive. The phrase 'existing archive' clearly distinguishes it from sibling tools like zip_create, and the mention of 'under their own names, or under prefix' captures the core operation.

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 description clearly establishes the context — adding to an existing archive — which implies when to use it versus creation, extraction, or listing tools. It does not explicitly name an alternative or state when not to use it, so it only falls short of full exclusion 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?

Annotations are all false and provide no meaningful behavioral constraints. The description adds useful environment context (hosted servers return one-hour download links and keep no output folder), but it says nothing about what happens when the tool does run—what file is produced, side effects, or overwrite behavior. 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.

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

Three short sentences, front-loaded with the hard constraint 'Local (stdio) install only.' It avoids repeating schema content and spends its length on the routing caveat. Compact, though one sentence stating the local behavior would have made it stronger.

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 tool with five optional parameters, no output schema, and no helpful annotations, the description provides crucial environment routing but omits the core local behavior and outcome. An agent can infer much from title and schema, but the definition is not self-sufficient and has clear gaps around what is produced and where.

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% and all five parameters have descriptions, so the description does not need to repeat them. It adds no parameter-specific meaning beyond what the schema already provides, matching the baseline.

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 never states the core action ('bundle a month of documents from sibling servers into a zip')—it relies on the title and parameter names. It does usefully narrow scope by naming the five servers and the hosted-endpoint caveat, but the main verb and resource are left implicit.

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?

Explicitly states the tool is local/stdio only, that on the hosted endpoint there is nothing to bundle, and names the exact alternative pathway (zip_upload plus zip_create). This is direct when/when-not/alternative 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?

The annotations are all false and carry little behavioral information, so the description bears the responsibility for disclosure. It adds meaningful traits beyond the schema: the resulting link expires in one hour, and entry names are always relative, preventing writes outside the unpack destination. This is useful, non-obvious behavior not available in annotations.

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?

Two concise sentences with no filler. The primary action and outcome are front-loaded in the first sentence; the second sentence adds an important security-relevant behavior. Every clause earns its place.

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 tool with 8 parameters, one required parameter, and no output schema, the description adequately covers the core behavior, the returned artifact (download link with one-hour validity), and a key constraint. The remaining parameter details are covered by the exhaustive schema descriptions, so nothing critical is missing for correct invocation.

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 this dimension is at baseline 3. The description adds no parameter-specific detail, but the input schema already provides rich explanations for every parameter, including refusal behavior for dir and password and the default for overwrite. The description does not need to compensate for any coverage gap.

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 names a specific verb and resource: 'pack files uploaded with zip_upload into a new .zip' and states the outcome ('get a download link valid for one hour'). It clearly distinguishes this from siblings like zip_upload (uploading) and zip_add (likely adding to an existing archive) by emphasizing that a new archive is created.

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 description opens with 'Call this tool to...' and clearly states the intended use case: packing previously uploaded files into a zip for download. It does not explicitly mention when not to use it or name alternative tools, but the purpose is specific enough that an agent can decide to invoke it.

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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful non-obvious side effect — that zip_history register rows are retained — which is exactly the kind of context annotations cannot express. It stops short of disclosing reversibility, permission requirements, or behavior when the file is missing.

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?

Two short sentences with the action front-loaded and the retention caveat second. The phrasing 'The register rows zip_history lists are kept' is slightly awkward but adds real information rather than padding.

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 single-parameter destructive tool with no output schema, the description covers the main destructive scope and the history-retention side effect. It leaves out error behavior and the exact meaning of the required name argument, which an agent needs to invoke it correctly.

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 single parameter 'name' carries no documented meaning beyond minLength/maxLength. The description never clarifies whether 'name' is a filename with extension, a path, or an identifier, nor whether it must match an existing uploaded file exactly. This is a real gap for the one input the agent must supply.

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 ('Delete one uploaded file') plus a scope qualifier ('stored for your token'), which distinguishes it from account-wide or bundle operations. It also implicitly separates itself from the zip_history sibling by noting that history rows survive. It does not, however, explicitly distinguish deleting an uploaded file from zip_add/zip_create/zip_extract operations on archives.

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 is only implied: the agent can infer this is for removing a previously uploaded file while preserving audit history. There is no explicit statement of when to use this versus zip_list/zip_history, nor any prerequisite or failure condition (e.g., what happens if the name does not exist).

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 all annotations false, the description carries the full burden of behavioral disclosure. It goes beyond annotations by detailing safety mechanisms (traversal/absolute-path/symlink refusal, zip bomb size and ratio caps, dry_run behavior) and the unusual output format (per-entry download links valid for one hour). It does not explicitly state whether it writes to disk, but the 'no directories' and download-link phrasing strongly imply a non-persistent extraction. This is substantial added context beyond the minimal annotation signals.

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?

Two sentences with zero filler. The core action is front-loaded, followed by the most critical behavioral notes (safety and output format). Every clause earns its place, and the structure makes the essential facts immediately visible.

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 an 8-parameter tool with no output schema and empty annotations, the description covers the key behaviors: extraction scope, safety guards, dry_run semantics, and the return format (download links). It does not enumerate default values (though those are in the schema) or error conditions, but for an agent deciding whether to call it, the essential information is present. The lack of an output schema is mitigated by the explicit statement about download links.

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 100% with descriptive parameter comments for all 8 parameters, so the baseline is 3. The description reinforces safety parameters (max_ratio, max_total_mb) and dry_run, but does not add format or syntax details beyond what the schema already provides. It does mention the out_dir is ignored (via 'no directories'), but that is already in the schema description. Overall, the description does not significantly augment parameter understanding.

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 opens with a clear verb+resource ('unpack an archive') and immediately distinguishes itself from sibling tools like zip_extract_text by noting every entry comes back as a download link, which is a unique behavior. This is specific enough that an agent can tell it apart without opening other tool schemas.

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 description states when to call it ('Call this tool to unpack an archive'), providing a clear context. However, it does not mention any alternative tools (e.g., zip_list for listing, zip_extract_text for text-only extraction) or any exclusions, so it lacks the explicit when-not-to-use guidance that would earn a 5.

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?

The description discloses key behaviors: it does not unpack anything, returns text inline, and refuses binary entries by name rather than printing noise. Since annotations provide no positive safety profile (readOnlyHint false, destructiveHint false, etc.), this behavioral detail carries value beyond the schema. It does not mention side effects (likely none) or permissions, but the provided traits are helpful and non-contradictory.

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 description is compact: two sentences that immediately state the invocation context and a key behavioral constraint. It is front-loaded with the core action ('read one text entry... without unpacking'), followed by a valuable edge-case note. No redundant or filler phrases.

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 small, focused read tool with three parameters and no output schema, the description covers the core capability, the no-unpacking behavior, and the binary-entry refusal. It does not mention return format details (though 'text comes back inline' gives a hint) or prerequisites like using zip_list to find entry names, but the schema's reference to zip_list partially covers that. The description is adequate for simple usage without major 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 100%, so the schema fully documents all three parameters. The description adds minimal semantic value beyond the schema—'give the entry name and the text comes back inline' simply reinforces the entry parameter's effect but does not specify formats, defaults, or edge cases beyond what the schema already states. Baseline 3 is appropriate.

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: 'read one text entry out of an archive without unpacking anything.' It clearly differentiates from zip_extract by emphasizing no extraction occurs, and the title 'Read one entry as text' reinforces the scope. An agent can distinguish this from siblings like zip_list (listing) and zip_extract (extracting) 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.

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

The opening phrase 'Call this tool to...' provides clear context for when to use it: when a single text entry is needed inline without extraction. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use zip_extract for binary files'), though the binary-refusal note implies such an exclusion. This is a clear context but lacks explicit sibling routing.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so safety is covered. The description adds genuinely new behavioral context: results are scoped to the caller's token/endpoint, sizes are included, and the returned names are the resolution basis for path arguments elsewhere. It does not mention ordering or result limits, which keeps it from 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?

Two short sentences with zero filler, and the core purpose is stated first. The second sentence earns its place by explaining what the output names are for.

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?

There are no parameters and no output schema, so the description carries little burden and it does disclose that sizes come back with each file. The one real gap is the unresolved relationship to the sibling zip_list, which an agent needs in order to route correctly between the two listing-like tools.

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?

The tool takes zero parameters, so there is nothing the description needs to disambiguate; baseline 4 applies. The description's only parameter-adjacent claim is about how the returned names are consumed by other tools, which is accurate framing for a no-arg call.

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 gives a specific verb and resource: "List the files stored for your token on this endpoint, with their sizes." It also clarifies what the returned names mean (they are the basis for every path argument). However, it never distinguishes this from the sibling zip_list, which an agent could plausibly read as the same operation.

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 sentence "These are the names every path argument here resolves against" implies this is the discovery step before path-based calls, but that inference is left to the agent. There is no explicit when-to-use, no when-not-to-use, and no mention of zip_list as the alternative.

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?

Annotations are all false, so the description carries the burden; it adds useful behavior: results are newest-first, the free monthly quota is shown, and download links expire after an hour while the row/name remains. It does not explicitly describe any side effects, but nothing in the description contradicts the annotations, and 'List' is consistent with the tool name.

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?

A single front-loaded sentence states the core purpose before adding scoping, ordering, result fields, quota, and retention/link-expiry behavior. Every clause earns its place; no filler or restatement of the title.

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 one-optional-parameter listing tool with no output schema, the description is complete: it names the returned fields, ordering, quota accounting, and link-expiry/retention behavior. An agent has enough information to invoke it and interpret the result correctly.

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 100% for the only parameter, limit, including bounds and default, so the description does not need to compensate. The phrase 'newest first' in the description aligns with the schema, but the description adds no parameter detail beyond it.

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 ('List'), a precise resource ('archives created for your token'), and the content of the listing (entry counts, sizes, names, quota use, newest-first). This clearly separates it from siblings like zip_create or zip_extract, which operate on archives rather than listing history.

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 description makes the intended use clear: retrieve the caller's archive-creation history with default/limited rows. It names the access scope ('for your token') and gives the context needed to choose it over mutation tools, but it does not explicitly name alternatives or state when not to use it.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description repeats 'Read-only' which is redundant but does not contradict. It adds valuable behavioral context beyond annotations: the tool flags dangerous entries (absolute paths, .., symlinks, encrypted entries, duplicate names, bombs) and is intended to run before zip_extract. This enriches the agent's understanding of what the tool does at runtime despite 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.

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

The description is two sentences plus a short fragment: it front-loads the core action and safety flags, then gives usage guidance. The standalone 'Read-only.' is redundant with annotations and could be folded in, but it is short and does not bloat the text. Overall it is tight and efficient with no filler, only the repeated annotation costs a small deduction.

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 list tool with no output schema, the description adequately conveys what the tool returns at a high level (entries with sizes/ratios plus danger flags) and notes that totals always cover every entry (in the limit parameter description). Combined with annotations covering safety, the description is sufficient for an agent to invoke it correctly before extraction. It could be more explicit about the exact return structure, but that is not essential for a listing operation.

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 each parameter (path, limit, patterns, max_ratio) already has a clear description. The main description mentions 'sizes and ratios' which relates to output and max_ratio, and 'flag what is dangerous' connects to the safety checks, but it doesn't add new semantic nuance beyond the schema. Baseline 3 applies because the schema carries the parameter semantics.

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 uses a specific verb and resource: 'list an archive's entries with sizes and ratios' and clearly defines the uniqueness via safety flags (absolute paths, .., symlinks, encrypted entries, duplicate names, bombs). It also names the sibling zip_extract for context, which differentiates it from a plain listing tool. The purpose is unmistakable and distinguishes the tool from the sibling set.

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 description gives explicit usage direction: 'Run it before zip_extract.' This tells the agent exactly when to invoke it as a pre-extraction safety check. However, it does not mention alternatives (e.g., zip_files) or state when not to use it, so it falls short of full 5 because exclusions and alternative routing are absent.

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?

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds substantial operational context beyond them: 10-second fetch timeout, max 3 redirects, public http(s) only, 1 MB cap, PK magic validation for .zip, per-token persistence between calls, and a 256 KB body cap yielding ~190 KB of paste. The one untouched trait is what 'destructive' means here — re-uploading an existing name replaces it — so a 4 rather than 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?

Purpose and the name-passing model are front-loaded, and the per-parameter elaboration is prefixed with 'url:' to keep it scannable. It is still a dense single block covering four parameters plus limits; the size-cap material could be compressed, but no sentence is genuinely filler.

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 4-parameter upload tool with no output schema, it covers the full lifecycle: storage scope (your token), limits, validation, listing and deletion. The remaining gap is the response behavior — whether the stored name is echoed back and what happens on a name collision — which matters given idempotentHint/destructiveHint.

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 100%, but the schema does not encode mutual exclusivity; the description supplies the critical rule 'Give exactly one of content_base64, content or url', plus that content is rejected for a .zip and that base64 is the sole paste form for archives. That is genuine meaning the schema alone would not convey.

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?

Names a specific verb and resource ('Send a file to this hosted endpoint') and immediately frames the unusual no-filesystem upload model that distinguishes it from all other zip_* siblings. The final clause routes the resulting name to zip_list/zip_extract/zip_add for archives and zip_create for plain files, so the agent can tell what this tool is for 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?

Explicitly states which downstream tool consumes the uploaded name depending on file type, and names zip_files for listing and zip_delete_upload for removal. It also gives a decision rule between content_base64, content and url (url recommended above ~10 KB, url not accepted for archives), which is exactly the when-to-use guidance an agent needs.

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