Mesh

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

With no annotations, the description carries the full burden, and it does disclose useful traits: required env vars, the fact that sync pushes state and pulls peers, and that push-file auto-notifies the peer. It does not cover write-safety (does pull overwrite local files?), secret handling, error semantics, or rate limits, and gives no return-shape hints despite there being no output 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?

Two headed sections backed by bulleted action glosses make a 22-action tool scannable, and the domain sentence is front-loaded. The legacy section is thinner than the remote one and there is some redundancy between action names and their parenthetical parameter hints, but there is little wasted prose.

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?

This is a 29-parameter, 22-action omnibus with no annotations and no output schema, so the description must carry the load. Three enum actions are undocumented, return behavior is never described for any action, and no Python of when a lock is needed or what sync/pull do to local state, leaving meaningful gaps for a tool this complex.

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 real value by mapping actions to parameter tuples (e.g., ask → to, question; reply → message_id, answer), but it omits the actions (task_lock, propose_intent, events) that own lock_action, intent_type, resource, ttl_ms, module, and peer_id, so those parameters have no action-level context in the description.

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 names the domain ('multi-instance communication and coordination') and enumerates every action with a short gloss, so the agent can see what the tool is for at a glance. However, it never differentiates itself from plausible sibling overlap (hive_coordinator, cross_session, task_transfer, hive_history), and several enum values (task_lock, propose_intent, events) are absent from the action list entirely, leaving parts of the surface unexplained.

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 remote-vs-local split plus the M7_MESH_RELAY/M7_MESH_SECRET/M7_WORKSTATION prerequisites and the 'init auto-detects remote if configured' note give real context for choosing a path. But there is no explicit when-to-use guidance between the described actions or against the mesh-like siblings, so an agent must still infer the selection.

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