hive_search

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 unusually well: it discloses compact no-body hits, inactive-entry hiding, degraded keyword-only mode, feedback counts, contested/correction/supersedes fields, foreign fleet handling, and explore ordering. An agent has substantial context about what results mean and how to interpret thin or ambiguous hits.

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 core purpose is front-loaded and most sentences carry useful behavioral detail rather than filler. However, it is a dense wall of parentheticals and terse field notes, which makes the result-field semantics harder to parse than necessary.

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 17-parameter search tool with no parameter descriptions, no annotations, and no output schema, the description is incomplete: it explains return-field concepts but omits most filter semantics, value formats, and pagination behavior. An agent can understand the tool's purpose and caveats but cannot confidently set many parameters.

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 0% across 17 parameters, so the description must compensate, but it only explains entities, include_inactive, recency, explore, and implicitly query. It leaves kind, tags, agent, limit, scope, author, offset, flagged, created_from/to, and occurred_from/to undocumented, making most filters opaque.

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 states a specific resource and method: hybrid keyword plus vector search returning compact hits without bodies. It explicitly distinguishes itself from hive_get, which is used to open a hit, and frames the filters and result semantics clearly enough to identify the tool.

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?

It gives explicit usage guidance for opening hits with hive_get, for include_inactive when superseded or withdrawn entries may matter, and for recency choices based on whether the answer will age. It does not explicitly contrast with hive_list or hive_pinned, leaving one sibling-selection gap.

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