universal-memory

Overview Schema Source Related Servers Discussions Admin

purge_fact

Destructive

Destructively remove one fact by ID or all facts in a selected project/global scope. Requires confirm=true; use list_facts first to identify records before deletion.

Instructions

Destructively remove one fact by ID or all facts in an explicitly selected scope. Use list_facts first to identify intended records; use context only for reading. confirm=true is mandatory; false rejects without purging. Supply id or scope, not both; omitting both is rejected. Project or unscoped ID lookup requires initialization. The configured repository uses safe writes for recovery; inspect list_snapshots and list_audit_events rather than assuming the response contains a snapshot ID. Returns purged_count, affected_ids, and an audit marker. Repeating a purge may fail if the fact no longer exists.

Input Schema

Name	Required	Description
`id`	No	Exact fact ID from list_facts. Selects one fact; omit when purging an entire explicit scope. Cannot be combined with scope.
`scope`	No	Explicit project/global scope to purge in full when id is omitted. Cannot be combined with id; omitting both is rejected.
`confirm`	No	Explicit destructive-operation authorization. Defaults to false, which rejects the operation without applying it.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.6.4Nov 5, 2026

addedInput schema / properties / confirm / description

Added value: +"Explicit destructive-operation authorization. Defaults to false, which rejects the operation without applying it."

addedInput schema / properties / id / description

Added value: +"Exact fact ID from list_facts. Selects one fact; omit when purging an entire explicit scope. Cannot be combined with scope."

addedInput schema / properties / scope / description

Added value: +"Explicit project/global scope to purge in full when id is omitted. Cannot be combined with id; omitting both is rejected."

First observedv0.4.0Jul 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: confirm=false rejects without applying, project/unscoped ID lookup requires initialization, and recovery must go through list_snapshots/list_audit_events rather than an assumed snapshot ID in the response. It also warns that repeating a purge may fail once the fact is gone, which directly explains the non-idempotent hint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The destructive scope constraint is front-loaded and every sentence carries information an agent needs. Some sentences are dense and run together (initialization requirement, snapshot/audit guidance, return fields), but there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive three-parameter tool with an output schema, the description covers preconditions, sibling routing, failure modes, and recovery paths in addition to (briefly) the return fields. An agent could invoke this correctly and safely without consulting another tool's docs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds semantics: it restates the id/scope mutual exclusion and the fail-if-both-omitted rule plus the mandatory confirm gate as operational constraints. It does not add format or sourcing detail beyond the schema, keeping it at a strong 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ("Destructively remove one fact") and immediately names the two supported selection modes (by ID or by explicit scope). This distinguishes it cleanly from siblings like list_facts, context, and remember_fact without requiring the schema to be opened.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes the agent: use list_facts first to identify records, use context only for reading, and confirm=true is required or the call is rejected. It also states the exclusivity rule (id or scope, not both) and that omitting both fails, so the invocation preconditions are fully spelled out.

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