Dispatch Build

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered externally. The description adds genuine behavioral context beyond that: the tunnel-manager dependency is optional, refusals are named and cause-preserving rather than raising ImportError, and host_loss_reconcile is unconditionally unavailable. However, it discloses nothing about the target operation's own side effects or required preconditions.

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 long, jargon-dense ('RMDD-15', 'CapacityInventory resource ledger', 'WorkItem-authoritative ResourceScheduler') and spends most of its length on module architecture and the refusal behavior of sibling operations. It is not front-loaded on what this tool does, so most sentences do not earn their place for the calling agent.

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 35-parameter, multi-operation tool with an output schema, the description never explains how one tool multiplexes register_worker/recheck/stage_source/dispatch_build or what dispatch_build requires end-to-end (a staged source, host_id, command argv). The most important routing and prerequisite information is absent.

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 every parameter carries a 'For <operation>:' note, so the schema fully documents meaning. The description adds no parameter-level semantics at all, which is the expected baseline of 3 when the schema does the heavy lifting.

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 line 'Dispatch build (rm_remote_workers)' merely restates the name/title, and the remainder describes the module's scope ('Remote worker registry, immutable source staging, and artifact transport') rather than this tool's specific operation. An agent cannot tell from the description what dispatch_build actually does that distinguishes it from rm_remote_workers_stage_source or rm_remote_workers_receive_artifact.

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?

There is no explicit when-to-use guidance versus the many rm_remote_workers_* siblings. The only conditional information is about failure modes ('refuse ... when it is absent', 'host_loss_reconcile always refuses today'), which describes other operations and never routes the agent to the right tool.

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