memory_graph_review

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description is consistent with them. It adds meaningful context beyond the annotations: 'forgets retire, never delete', that relate writes the relation edge and dismisses the pair, and what accept_merge/accept_junk actually do to data. It stops short of disclosing auth/permission needs or irreversibility per action.

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?

Purpose is front-loaded in one sentence, followed by a scannable action list and a one-line return note. The awkward indentation and the split of some entries across lines cost a little, but there is no filler and each line carries information.

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?

An output schema exists, so the brief 'per-action dict; {error} on bad input' note is sufficient. All 11 enum values are described, and with 0 required params the default of `list` is implied by the description. Missing only per-action required-parameter hints, which would help an agent call non-default actions correctly.

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 89%, so the schema already documents nearly every parameter and even maps params to actions (e.g. 'relate/dismiss_pair: the first entity'). The description's param mentions ('store + src (the retired key)', 'settle an edge proposal by id') largely restate the schema, so the baseline 3 applies.

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?

States a specific resource (the graph review queue) and frames it as 'deep-dream proposals that need a verdict before they touch the graph', then enumerates all 11 actions with one-line semantics. It distinguishes itself from siblings like memory_consolidate and memory_dream by tying the queue to dream proposals, but it never disambiguates the `relate` action from the sibling tool memory_graph_relate, which appears to write the same kind of edge.

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 per-action lines imply when each action applies ('relate' for related-not-duplicate, 'accept_junk' for over-extraction artifacts), which is real guidance. However, there is no explicit when-to-use-this-tool-vs-alternatives statement, no prerequisites or ordering, and no indication of which actions require which params before calling.

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