search

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds value by revealing the output includes a confidence flag and reasons, and mentions that 'context-dependent recall and all retrieval mechanisms apply', which hints at behavioral complexity. However, it does not explicitly state whether the operation is read-only, whether it has side effects, or what 'all retrieval mechanisms apply' concretely entails, leaving some ambiguity.

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 compact, consisting of a single sentence with a parenthetical. It front-loads the primary purpose and packs in the return details without unnecessary fluff. The parenthetical is slightly vague but does not waste words, making it efficient.

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 the simple schema (3 strings), no annotations, and no output schema, the description provides a reasonable overview of core functionality and return values, which helps the agent understand what to expect. However, it is incomplete in explaining the 'context' parameter and lacks usage guidance relative to many similar sibling tools, so an agent may struggle to choose this tool appropriately or construct the context input.

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 has no parameter descriptions (0% coverage), so the description must compensate. It clarifies 'query' (the search input) and 'top_k' ('returns the top-k matches'), but the 'context' parameter is only indirectly referenced via 'context-dependent recall' without explaining its format, optionality, or effect. This leaves a significant gap for the agent to know how to populate the context parameter correctly.

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 clearly identifies the tool's function: 'Retrieve memories for a query' with a specific resource (memories) and action (retrieve). It also details the return format (top-k matches with content, score, confidence flag, reasons), making the purpose specific. However, it does not explicitly differentiate from sibling tools like 'search_batch' or 'recall', though the top-k scoring detail implies a single-query ranked search.

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 provides no guidance on when to use this tool versus alternatives such as 'search_batch', 'recall', or 'remember'. It lacks any mention of prerequisites, exclusions, or context in which this tool is preferred. The only hint is 'context-dependent recall', but it doesn't explain practical usage scenarios or boundaries.

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