AgentParcel MCP Server

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with "Read-only" while adding substantive detail about what each inspection yields (entry counts, oversize entries, estimated part count, part n of N, present/missing parts, readiness to rebuild). With no output schema, this per-type return description is genuinely load-bearing; only error/nonexistent-path behavior is unaddressed.

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 read-only guarantee, then organized as four parallel "For a X:" clauses, each carrying distinct information with no filler. Slightly longer than minimal, and the opening "Read-only" restates the annotation, but no sentence is wasted.

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 four optional parameters, no output schema, and a multi-modal input, the description does the work of documenting return content per input type, which is the main gap it needed to fill. Missing only edge-case behavior (invalid/missing paths, what happens when the zip is encrypted or malformed) to be fully complete.

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 the schema already documents path, max_mb, preset, and max_bytes in far more depth than the description does. The description adds only indirect context by referencing max_mb in the part-count estimate; it never explains presets or max_bytes, so it does not go beyond the schema. Baseline 3.

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 (inspect a path) and then enumerates exactly what is reported for each input type: zip, AgentParcel part, folder, plain file. This makes it trivially distinguishable from siblings like split_zip, rebuild, and verify, which act on the same resources.

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?

"Look at a path before splitting or rebuilding" gives a clear when-to-use context that ties it to split_* and rebuild. It also states the hard constraint that paths must be absolute. It does not explicitly contrast with verify (the other read-ish sibling) or say when not to use it, so it falls short of 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?

Annotations cover the safety profile (non-readonly, non-destructive, non-idempotent), and the description adds real value beyond them: append-on-collision naming ' (2)' (which explains the non-idempotent hint concretely) and the fail-if-too-large behavior. It stops short of saying what the return value contains or where parts land.

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?

One tight sentence front-loads the artifact and destination, then adds collision and size-limit behavior. No 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 no-output-schema write tool, the description covers destination, contents, collision behavior and size failure modes. The one gap is what is returned (paths/names of written files, whether multiple parts are produced), which matters given the 'parts' language and sibling splitting 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?

Schema coverage is 100%, so baseline is 3, and the description adds the important semantic that max_mb/max_bytes cause a failure rather than a silent split. Slight tension with the schema wording 'Max size of each part', which suggests multi-part output, but the extra fail-fast semantics still earn above 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?

States a concrete verb and artifact: writes AgentParcel-apps.zip into output_dir, and enumerates the contents (Windows/Mac/Linux builds, this MCP server, HOW TO REBUILD.txt). It is clearly distinct from split_*/verify/rebuild siblings, though it never names them explicitly.

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 phrase 'so a human who receives parts can rebuild them' implies the use case, but there is no explicit when-to-use versus when-not, and no routing to siblings like split_zip or rebuild. An agent must infer the workflow position.

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?

Beyond the annotations, the description discloses the verification method (per-file size + SHA-256), the failure contract (names missing_parts / missing_names / corrupt_parts), the AgentParcel-apps.zip exclusion, and that output never overwrites. This is exactly the mutation-adjacent behavior an agent needs and is consistent with destructiveHint=false.

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 action, then input forms, then failure semantics, then the extract caveat — every sentence carries information. It is dense and terse to the point of reading like notes, but there is no 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?

With an output schema present, return-value detail is not required, and the description covers inputs, verification, failure naming, and non-overwrite behavior. The one soft spot is what happens on a collision ('never overwrites') — whether that is an error or a renamed output is left implicit.

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%, so the baseline is 3; the description adds meaning by clarifying that extract applies only to rebuilt zips and not to byte-split files, and that password is unnecessary for zip/plain sets. It still doesn't elaborate on output_dir behavior beyond what the schema states.

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 (rebuild the original from AgentParcel parts) and immediately disambiguates the two supported input families: zip part sets and byte-split sets. It is clearly the inverse of the split_* siblings and is distinguishable from verify (which checks without reconstructing).

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?

It spells out the three acceptable ways to supply parts (folder, any single part, explicit list) and scopes extract to zip sets only, explicitly excluding byte-split files. It doesn't explicitly say when to prefer it over siblings like verify or regenerate_parts, but the context of use is unambiguous.

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?

Goes well beyond the annotations: matched parts are left untouched, a zip layout mismatch replaces nothing and returns a corrective error, an encrypted set requires a password that is not stored, and still_needed reports residual gaps. That is exactly the destructive-scope and failure-mode detail the destructiveHint=false / idempotentHint=true annotations cannot convey.

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 behavior and every sentence carries real information – scope, zip caveat, password, return field. The final still_needed sentence feels appended rather than integrated, a minor structural wrinkle in an otherwise tight paragraph.

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 is no output schema, so the description must explain returns, and it does (still_needed for remaining gaps, an error message for zip mismatch). Combined with annotations covering write/idempotency and full schema coverage, an agent has everything needed to call this 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 100%, so all four parameters are already documented (parts as folder/one part/all parts, original, password, part_numbers). The description mainly restates those roles ('or the part_numbers you list', 'An encrypted byte set needs password') without adding format or edge-case guidance beyond them, so the baseline of 3 applies.

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 first sentence names a specific verb ('rewrite') and a precisely scoped resource ('only the parts that verify reports as missing or corrupt'), plus the optional override. That scope cleanly separates it from siblings like split_* (which create parts) and verify (which only reports).

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?

It states the precondition clearly ('given the original file and an existing part set') and the reason to pick it over a full re-split ('so you can upload just the replacements'). It also covers the failure branch – a mismatched zip layout means a full re-split is required. It never names the sibling tools (verify, split_zip, rebuild), so the routing is implied rather than explicit.

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 annotations declaring readOnlyHint=false and destructiveHint=false, the description still adds substantial behavioral context: parts are raw (not zips), the output folder gains _agentparcel_bytes.json, HOW-TO-REBUILD.txt and rebuild.py, and SHA-256 verification occurs on rebuild. It also flags that password encryption requires the cryptography package and that the password is never written to manifest/log — none of which annotations supply.

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-loads the core purpose ('Byte-level split of ANY file') and the critical properties ('Parts are not zips') before elaborating. Slightly dense with parentheticals and file-name lists, but every clause contributes either scope, output contract, or routing.

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?

Output schema exists, so return values need not be described; the description instead covers the on-disk artifacts a caller must know about (numbered parts, manifest, rebuild script). For a 9-parameter mutation tool with an output schema, the description supplies enough to call and interpret results 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 100%, so the baseline is 3; the description adds meaning beyond the schema by explaining the effect of compress (rebuild.py decompresses using stdlib) and the relationship between max_mb/max_bytes and presets in the surrounding prose. It stops short of fully documenting every parameter in the description body, but the schema carries that weight.

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+resource ('Byte-level split of ANY file ... into numbered raw parts'), and clarifies what the parts are not ('Parts are not zips'). It explicitly names the sibling tools (split_zip, split_files) and the condition that selects them, so an agent can distinguish it without opening any 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?

Gives explicit routing: 'Use split_zip or split_files when you want standalone zip parts', and the description of presets says how to pick part sizes per platform cap. The presence of rebuild.py and HOW-TO-REBUILD.txt tells the agent this is the path for recipients who cannot use AgentParcel.

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 cover the safety profile (not read-only, non-destructive, non-idempotent, closed-world), so the description's added value is the behavior: no permanent full zip is written, folders keep structure, an oversized single file is cut into .001/.002 pieces inside consecutive parts, and every part's absolute path and size is returned. It could have noted that repeat runs land in numbered '<name>_split (2)' folders, which is idempotency-relevant, but that is covered in the schema.

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 usage trigger, then output shape, then the edge case, then the rebuild path. Four dense sentences with no filler; every clause carries information the agent needs.

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 9-parameter mutation tool with annotations and an output schema, the description covers the trigger, the archive/parts output contract, single-file splitting, and the recovery tool. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema coverage is 100%, so a 3 is the baseline. The description still adds meaning by tying archive_name to the '<archive_name>.zip' output naming and by explaining how max_mb interacts with a single oversized file (split into .001/.002 pieces inside consecutive parts), which the per-property text does not spell out.

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 ('Packs the inputs into <archive_name>.zip ... and splits it into standalone zip parts') and scopes it precisely with 'files or folders that are not a .zip', which cleanly separates it from split_zip and split_any_file. An agent can pick it without opening the 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?

'Use when files or folders that are not a .zip are too big to upload' gives a concrete trigger, and 'Rebuild with the rebuild tool (extract=true gives the files back as a folder)' points to the reverse operation. The exclusion is expressed as a condition rather than by naming split_zip, so the sibling routing is implied rather than explicit.

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?

Goes well past the annotations: it guarantees no data loss ('files are never cut unless a single file is bigger than a part'), specifies the naming scheme and the .001/.002 fallback, states 'Never overwrites anything', and describes exact rebuildability via SHA-256 with the rebuild tool. It is consistent with destructiveHint=false and readOnlyHint=false (files are created, nothing is destroyed).

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 trigger, then the output contract, then the rebuild and sibling routing. Every sentence carries distinct information, though the parenthetical about single-large-file .001 pieces and the rebuild note make it denser than strictly needed.

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 an output schema and full param coverage, the description still covers what an agent most needs to know: how many files come back, that all must be uploaded, that the original is exactly recoverable, and that nothing is overwritten. No meaningful gap remains for an 8-param tool.

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 the preset enum is documented param-by-param with byte values, so the schema already carries the semantics. The description only reinforces the max_mb-per-part constraint and part naming, adding little beyond structured fields; baseline 3 applies.

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 ('Splits it into parts named <name>_part01.zip...') and immediately bounds scope by excluding non-zip inputs in favor of split_files. An agent can distinguish it from split_files and split_any_file 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?

Gives the triggering condition ('Use when a .zip is too big to upload/attach') and an explicit exclusion with the alternative named ('For anything that is not a .zip ... use split_files'). It also warns the recipient-side requirement ('upload all of them'), which shapes how the caller should proceed.

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?

Beyond the readOnlyHint annotation, the definition adds real behavioral context: it does not write any output file, ok is false when something is wrong, and the missing_parts, missing_names, and corrupt_parts fields name the specific parts. The rule "A part that fails its SHA-256 is corrupt, not missing" resolves an ambiguity in error classification that the schema and annotations cannot express.

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?

Five short sentences, with the purpose first, then the scope exclusions, then the supported formats, then the failure semantics. Every sentence adds information, and none is filler or redundant.

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 that verifies multi-part files across formats and has an output schema, this covers the format matrix, the fact that it is read-only, and the structure of the error and partial fields. Nothing an agent needs in order 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.

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

Schema coverage is 100% and the parts parameter already documents its accepted forms, including the single-string case. The description adds only indirect support through the manifest filenames, without expanding on the path forms. Under those conditions, a baseline 3 applies.

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 opening sentence names the operation and resource ("Confirms every part is present and each part's checksum matches the manifest"), which is a specific statement of intent. The later sentence "Does not write a rebuilt file" cleanly separates this tool from rebuild and from a plain inspect.

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 phrase "Read-only check before rebuild" sets the situation clearly, and the supported manifest formats tell the agent when the tool applies. However, it never points to a sibling by name (inspect, rebuild, regenerate_parts) as an alternative, nor does it state any case where it should not be used.

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