Skip to main content
Glama
Sign In
quipu

quipu

Official
by intigraph
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Hybrid

quipu_retract_source

Destructive

Retract all live facts whose transaction source exactly matches a given string; preview by default, then confirm with expected count to apply.

Instructions

RETRACT-ONLY repair: retract every currently-live fact whose transaction source equals an exact string. Reaches facts that no snapshot replacement can touch — quipu_knot composes its own tag as snapshot:, so facts written under any other source (a free-form producer string, a hand-run CLI promote) were previously unretractable forever. There is NO turtle input: the transaction cannot carry an assertion, so this cannot write facts attributed to the named producer. The retraction is stamped with its OWN source, repair:, never the source being cleared. PLANS BY DEFAULT: without apply=true it writes nothing and reports what would be retracted, so planned:0 means 'that source owns nothing live'. Applying requires expect= as a confirmation handshake, and the response reports 'remaining' — a fresh read of the post-state, not an echo of the request. RE-KEYING ORDER: retract FIRST, then re-promote canonically; asserting first is skipped as a duplicate and the retraction then removes everything.

Input Schema

NameRequiredDescriptionDefault
actorNoWho is performing the repair
applyNoDefault false = plan only, nothing is written. true commits the retraction and requires 'expect'.
graphNoOptional registered committed-graph IRI; absent targets ROOT. Same graph rules as quipu_knot.
expectNoRequired with apply=true: the planned count you are confirming. A mismatch is refused — the store moved, or this is not the source you measured.
repairYesTicket or reason. Stamped on the retraction transaction as repair:<ticket>, so the log records who cleared these facts and why.
sourceYesEXACT transaction source string to retract. Matched literally — never by prefix or pattern. Read it from GET /transactions or an entity's history.
timestampNoISO-8601 timestamp for the retraction

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.17.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, it discloses critical behavior: plan-only default, the expect confirmation handshake, that 'remaining' is a fresh post-state read, that the retraction is stamped with repair:<ticket> rather than the cleared source, and the re-keying order. This is exactly the contextual depth needed for a destructive mutation.

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 definition is front-loaded with the core purpose and each subsequent paragraph addresses a distinct operational concern. It is dense but nearly every sentence carries necessary information. Minor verbosity from all-caps emphasis and repetition of plan/apply behavior keeps it from a 5.

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, source-scoped retraction tool with no output schema, the description covers the full operational picture: plan vs apply, confirmation requirements, return semantics ('remaining'), graph scope, and correct sequencing for re-keying. Nothing an agent needs to avoid a harmful call is missing.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics: source is matched literally (never by prefix), apply defaults to plan-only, expect must match the planned count, and repair is stamped as repair:<ticket>. It slightly exceeds the schema's already strong documentation.

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 description opens with a specific verb and scope: 'RETRACT-ONLY repair: retract every currently-live fact whose transaction source equals an exact string.' It explicitly distinguishes itself from snapshot replacement via quipu_knot and explains the gap it fills for facts written under other sources.

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

Usage Guidelines4/5

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

It provides clear context for use (repairing facts unreachable by snapshot replacement), states exclusions ('NO turtle input', cannot write facts attributed to the named producer), and gives ordering guidance (retract first, then re-promote). It does not explicitly contrast with sibling quipu_retract or quipu_retract_episode, so it falls short of full alternative routing.

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

Deploy Server

Other Tools