Dream: consolidate the memory store

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

Goes well beyond the annotations: names the survivorship rule (project layer wins, profile copy moves to archive/), asserts nothing is deleted, states the out-of-band recovery path (bantamkit-memory restore <name>), and flags the blast radius that the archived copy stops answering for every other project on the machine. This is consistent with destructiveHint=true while clarifying that 'destructive' here means archive-and-move, not deletion.

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?

Front-loaded with the verb and the core rule, and every clause carries operational content. It is nonetheless dense and long for a one-boolean tool, with some rhetorical framing ('never a winner-takes-all', 'what it buys is one copy of a ruling instead of two') that could be trimmed.

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?

With an output schema present, return values need not be explained, and the description covers everything else an agent needs: default behavior, safety impact, recovery route, sibling alternatives, and the reason the merge is done at all. Nothing material is missing for a destructive one-parameter 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?

Schema coverage is 100% and the single dry_run parameter is fully described there, so the baseline applies. The description still adds workflow meaning — that the default is a preview, that true performs all reads and merges but writes nothing, and that the agent should call twice (preview then apply).

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 verb and resource: consolidating memories held by the project layer and machine-wide profile layer under the same name, then reporting what changed. It spells out the three resolution outcomes (byte-identical collapse, divergent union, relative-date annotation) and names the surviving location, so an agent knows precisely what the operation does.

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?

Explicitly routes away from siblings: 'For room in the index call memory_compact instead; for the facts themselves, memory_recall.' It also gives the required call sequence — read the plan first, then re-call with dry_run false — and warns that the default dry run exists because the profile store is machine-wide.

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