gnosys_hybrid_search

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

Annotations only declare safety flags; the description adds real behavioral context beyond them – the shape of the return (scores, status, dates, replacement links), defaults for mode/limit/activeOnly, and prerequisite toolset state. The one gap is that annotations set readOnlyHint=false and idempotentHint=false while the description reads as a pure query, and it never explains what side effect or non-idempotency an agent should expect.

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-loads what the tool does and what it returns, then compresses the sibling routing and prerequisites into single clauses with no filler. Every sentence carries either a routing decision or a setup requirement.

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?

With no output schema, the description correctly takes on the burden of describing return values and does so concretely. It also covers the toolset-unlock and reindex setup path; the only shortfall is that it doesn't account for the non-read-only, non-idempotent annotation profile.

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 already documents mode, limit, activeOnly and projectRoot defaults, so most of the description's parameter talk is repetition. The worked example ({"query":"JWT refresh flow","mode":"keyword","limit":5}) and the recall/read routing add modest value, but projectRoot's gnosys_init error path is left entirely to the 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 ('Search memories by keyword and meaning') plus the exact return payload (ranked snippets, IDs, scores, status, dates, replacement links). That return-field list and the mode vocabulary let an agent distinguish it from gnosys_recall and gnosys_read without opening either 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?

Explicitly routes to alternatives with conditions: gnosys_recall for a context block, gnosys_read for a full body, gnosys_search for plain keyword, gnosys_federated_search for scope boosts, gnosys_discover for metadata only, gnosys_semantic_search for embedding-only. It also states the toolset gating required to see those specialists and the extra steps (full toolset then gnosys_reindex) for embedding setup.

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