hive_write

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

With no annotations supplied, the description carries the full behavioral burden and does so: scope defaults and out-of-permission rejection, supersede permission asymmetry (self vs fleet), supersede_denied aborting the whole write, 'check': true storing nothing, and the reply's 'related'/'warnings' fields. Also discloses a non-obvious failure mode (embedding_unavailable) with guidance.

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?

Front-loaded with the core action and densely packed with no filler sentences; the body-by-kind guidance and the write-decision rules each earn their place. It is delivered as one undifferentiated block, though, which makes scanning harder than a short bulleted structure would.

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?

Given 13 parameters, no annotations, and no output schema, the description explains the return fields (related with similarity, warnings) and the dry-run behavior, which covers what the structured data omits. The remaining shortfall is the four undocumented parameters, most notably payload and occurred_at.

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 0%, so the description must compensate and does for most parameters: scope, supersedes, importance (with a 1-5 rubric), sources shape and the path|url|session|other enum, see_also limits, body-by-kind content guidance. However tags, agent, payload, and occurred_at (4 of 13) receive no mention anywhere, which is a real gap for a low-coverage schema.

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?

States a specific verb and resource — 'Write a distilled entry (fact|insight|decision) into the shared pool' — and immediately names the sibling alternatives (hive_feedback for denied supersedes, hive_get for links). An agent can distinguish this from hive_search/hive_withdraw without opening the schema.

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?

Gives explicit decision rules: if an entry already says the same, don't write (withdraw yours if stored); if it replaces one, use 'supersedes'; if it adds a point, use 'see_also'; use hive_feedback when a supersede target is denied; don't retry in a loop on embedding_unavailable. Both when-to-use and when-not-to-use are covered.

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