memory_search

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

With no annotations, the description carries the full behavioral burden and does disclose meaningful traits: FTS usage 'when available' (implying a fallback path) and the OR/AND matching behaviors. This goes beyond what the schema shows. It does not, however, disclose the scope of the search, fallback behavior when FTS is unavailable, or result ordering.

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 entire description is a single efficient sentence with the verb and resource front-loaded and no filler. Every phrase — FTS, OR default, strict AND — adds information. It is appropriately sized for readability, though it is arguably under-sized given the number of undocumented parameters and siblings.

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 4 parameters with 0% schema coverage, no annotations, and a large sibling set containing several similar retrieval tools, the description is not complete enough for correct selection and invocation. An agent cannot tell when to prefer memory_search over memory_recall or memory_probe, nor what category filtering or limit behavior entails. The presence of an output schema helps, but the selection and parameter gaps remain.

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%, so the description must compensate, but it only partially does. It clarifies the mode parameter (OR default vs strict AND matching) and implicitly covers query, yet it says nothing about the limit or category parameters, and it never spells out the accepted mode values. For a tool with 4 parameters fully undocumented in the schema, this is insufficient.

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 verb and resource ('Search memories') and adds distinctive technical details: FTS-based matching, OR ranking by default, and strict AND as an alternative. This is clearly more than a tautology and gives the agent a concrete sense of the operation. However, it stops short of explicitly differentiating from retrieval siblings like memory_recall and memory_probe.

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?

No guidance is given on when to choose memory_search over the numerous retrieval-adjacent siblings (memory_recall, memory_probe, memory_list, memory_inspect). The description explains matching semantics but never states a use case, exclusion, or condition that would route an agent to this tool versus an alternative.

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