dispatch_send

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

Annotations only establish readOnlyHint=false and destructiveHint=false — the description goes far beyond them by disclosing real side effects: exact files written (meta.json, assignment.md), target directory ($WILLOW_HOME/dispatch/), the envelope/quota-gated Postgres exception (#333), and the dispatch_id-carrying return value. This is exactly the kind of state-mutating behavior an agent can't infer from 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?

Approximately 110 words and every clause earns its place: behavior → file artifacts → key params → lifecycle → edge case → return value. The 'Filesystem-backed unless an authority envelope...' sentence is syntactically dense but compact for the nuance it packs.

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 agent deciding whether to use this tool, the description is sufficient — it explains what happens, where, under what authority exception, and what comes back. But there's no output schema to fill the void, leaving the return shape partly inferential, and the valid phase values/context_refs format are pure guesses. It clears the bar but leaves real 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?

With 0% schema description coverage, the description is the sole documentation and it covers only 2 of 9 parameters — 'assignment_md is the full brief; reply_to names who verifies the handoff.' The highest-risk params (context_refs, phase) get zero help, and the schema only provides defaults for the others. Useful where it lands, but it's less than a quarter of the parameter surface.

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?

Opens with a specific verb+resource: 'Create a dispatch packet assigning work to another agent.' It clearly distinguishes itself from its sibling family through the lifecycle ('advances pending → working → complete via dispatch_accept and handoff_write_v4'). Naming the written files (meta.json, assignment.md) and directory cements the artifact contract.

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 context is clearly implied and scaffolded: it's the creation step in a state machine whose continuation steps are dispatch_accept and handoff_write_v4, which is exactly the decision boundary an agent needs. However, it never explicitly enumerates when not to use it or points to an alternative by name — the agent must infer exclusions from the visible sibling list.

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