memory_read

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that retrieval uses 'embedding similarity', implying a semantic search rather than exact match, which adds useful context. However, it does not mention side effects (likely none), performance considerations, rate limits, or fallback behavior. It also fails to note that the 'limit' parameter controls result count or that the tool can also retrieve by ID ('item_id'). For a read tool with no annotations, this is moderately transparent, hence a 3.

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 a single sentence, making it very concise. However, the structure is minimal—no hierarchical breakdown, bullet points, or separation into sections. For a tool with 7 parameters, the conciseness sacrifices necessary detail. The sentence earns its place but could be expanded without losing efficiency. A score of 3 reflects adequate conciseness but poor structure for the complexity.

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 tool's complexity (7 optional parameters, 0% schema description coverage, and presence of an output schema), the description is far from complete. It fails to explain the two retrieval modes (query-based via 'query' and exact-match via 'item_id'), the role of 'graph' and 'level' in scoping, or the interaction with 'agent_id' and 'session_id'. The output schema exists but is not referenced. The agent cannot fully understand how to use the tool effectively; a score of 2 captures this incompleteness.

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 by explaining the parameters. It does not mention any of the 7 parameters (graph, level, limit, query, item_id, agent_id, session_id), leaving their purpose entirely to the schema. The schema itself lacks descriptions, so the agent receives no guidance on how to use each parameter. This is a critical gap, warranting a score of 1.

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 'Retrieve from multi-graph memory with embedding similarity' clearly states the action (retrieve) and resource (multi-graph memory), and specifies the method (embedding similarity). It distinguishes this tool from siblings like memory_write (write) and memory_consolidate (consolidate). However, it does not specify the exact form of the returned data (e.g., a list of memory items) or differentiate from plan_cache_get, which also retrieves data. While clear, it could be more specific about the output, so a 4 is appropriate.

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. There is no mention of prerequisites, exclusions, or competing tools (e.g., plan_cache_get for plans, or item_id-based vs. query-based retrieval). The agent receives no help deciding between memory_read and other tools, resulting in a score of 2.

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