moa_handoff_send

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

With no annotations, the description fully discloses behavioral details: storage path ('handoff/<id>'), fromProject derivation, agent-level tagging and filtering, the silent-misspelling compromise, and the pull-on-demand consumption model. This goes far beyond basic expectations and helps the agent understand side effects and limitations.

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 relatively long but front-loaded with the primary purpose. Every sentence contributes necessary information (storage, addressing, limitations, non-indexing). It could be more terse, but given the complexity of the handoff semantics, the length is justified and well-organized.

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 and no annotations or output schema, the description is remarkably complete. It covers the write path, agent addressing, failure mode (misspelled addresses), and non-indexing behavior. The only minor gap is lack of any mention of return value or acknowledgment, but that is not critical for 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 coverage is 100%, so baseline is 3. The description adds meaning for parameters like toAgent/fromAgent (v2 addressing, opaque shape-checked, no registry) and context (96KB cap), plus the 'user-global' option for toProject. It doesn't extensively elaborate on workspace, but the schema already defines it; overall it adds real semantic value.

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 clearly states the tool's purpose: 'Send a directed handoff ... into the TARGET project's inbox.' It identifies the specific verb (send), resource (handoff), and target (toProject or user-global), distinguishing it from sibling tools like moa_handoff_inbox, read, consume, and archive.

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 when to use this tool (directed handoff vs. other messaging or persistence tools) and explicitly notes exclusions: 'Handoffs never participate in recall/indexing and never merge projects.' It doesn't name alternative tools, but the behavioral constraints effectively guide when to choose this over board_write or recall-based tools.

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