search_memory

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

With no annotations provided, the description carries the transparency burden. It discloses that results are ranked by similarity, that ranking is stable for pagination, that pages don't overlap or skip, and that offset past the last match returns no results. This is meaningful behavioral detail beyond the schema. It doesn't explicitly say the operation is read-only, but 'search' strongly implies no mutation.

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 description is tightly written in three short paragraphs. The core purpose is front-loaded, the example earns its place, and the pagination notes add essential operational detail without fluff. Every sentence contributes something actionable.

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?

The tool has an output schema, so there is no need to restate return values. The description covers what the tool searches, how results are ranked, how to page reliably, and what happens at the end of results — all an agent needs to call it correctly. Combined with full schema coverage, this is complete for a search tool.

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?

The schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the offset/limit relationship ('advance offset by limit — ranking is stable'), clarifying query semantics with a natural-language example, and noting edge behavior for out-of-range offsets. This goes beyond the schema's minimal field descriptions.

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 opens with 'Find memories by meaning' and clarifies this is semantic search over everything stored, with a concrete example ('what database did we pick?' → 'we went with SQLite'). This clearly distinguishes it from siblings like recall_memory or list_memories, which likely operate on exact identifiers or literal listings.

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 description gives a clear usage context: use it when you want to find memories by meaning rather than exact wording, and it explains pagination behavior. It does not explicitly name alternatives or state when not to use it, but the semantic-search framing makes the primary use case obvious enough.

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