Create handoff packet

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

Annotations only indicate non-read-only, non-destructive, and non-open-world behavior; the description adds substantial transparency: writes to the outbox, copies files as artifacts, requires at least one recipient, secret-scans content before writing, and does not transmit. This goes well beyond the structured hints and provides the key side-effect and safety context an agent needs.

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, front-loaded with the primary use, and every clause earns its place: the outbox write, artifact copying, returned path, recipient requirement, secret-scan, and no-transmission behavior. No filler or repetition of schema details.

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 18-parameter tool with no output schema and minimal annotations, the description gives a solid workflow overview and critical constraints, but it does not address the seed variant, private vs project outbox, or error/warning behavior such as NOTCH_SUMMARY_LARGE. The rich schema compensates for most parameter-level details, so the gap is modest.

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?

Input schema covers all 18 parameters with individual descriptions, so the baseline is 3. The description adds meaningful high-level constraints not explicit in the schema's required list: at least one recipient field is mandatory, and 'copies any listed files in as artifacts' ties the files parameter to the described behavior. It doesn't elaborate on individual parameter syntax because the schema already handles that.

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 specific action ('capture the current working state as a portable packet'), then details exact mechanics: writes a Markdown record to the store outbox, copies listed files as artifacts, and returns the packet with its path. It distinguishes create_packet from send_packet by noting 'creating a packet transmits nothing — packing and sending are separate steps.'

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 clear context for when to use the tool: when you need to capture working state for another session, tool, or repo, and explicitly states that no transmission occurs, implying sending is a separate step. However, it does not name sibling tools like send_packet or create_seed_packet as alternatives, so exclusions are 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.