open_memories

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

With no annotations provided, the description carries the full burden, and it delivers substantial detail: pagination behavior, maximum of 100 IDs, error raises (ValueError), not_found list in the return, and options to include relations/scores. It explains the structure of the return dictionary including pagination metadata. This well exceeds typical transparency.

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 well-structured with separate sections for summary, pagination note, args, returns, examples, and raises. Each section is informative and non-redundant, and the length is justified given the 5 parameters and pagination complexity. It is front-loaded with the primary purpose.

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 is moderately complex with pagination, multiple optional flags, and error handling, and the description covers all of these: parameter meanings, return structure, error conditions, and usage examples. It even includes a maximum ID count and pagination navigation examples. Given the output schema exists, the return structure section adds extra context without being required.

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%, but the description thoroughly compensates by explaining each parameter with syntax, constraints, and defaults: memory_ids accepts single or list up to 100, page is 1-indexed with default 1, page_size max 100, include_scores means decay scores and age, and include_relations means relations from/to. It also clarifies the schema's null defaults by specifying actual defaults.

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 'Retrieve specific memories by their IDs,' which clearly identifies the verb, resource, and retrieval method. This distinguishes it from sibling tools like search_memory (query-based) and read_graph (graph traversal). The reference to the MCP memory server's open_nodes functionality adds further context.

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 establishes that this tool is for retrieving memories when their IDs are known, which is clear usage context. However, it does not explicitly exclude alternatives or name sibling tools for contrasting cases, such as using search_memory when IDs are unknown. The 'Similar to open_nodes' reference provides orientation but no direct when-to-use vs. when-not-to-use guidance.

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