Skip to main content
Glama
ianderso

gramps-evidence-mcp

by ianderso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

merge_objects

Destructive

Merge duplicate Gramps objects by re-pointing all references from one record to another and combining their lists in one reversible transaction. Dry-run to confirm they represent the same thing.

Instructions

Merge two objects that are the same thing. Dry-run by default.

This uses Gramps' own server-side merge: every reference to drop is re-pointed at keep and the subordinate lists are unioned, in one transaction. Do NOT do this by hand: a manual merge that misses one of the lists the dropped object carries loses what was on it.

Before merging, be sure they really are one thing. Two records OF the same event are two documents: an index entry and the register page it indexes stay separate, and merging them would turn two independent citations into one, silently weakening every fact that rested on both. Conversely, the same census page entered once per household member IS one document, and leaving the duplicates makes single-sourced facts look corroborated.

Reversible: the merge is one transaction, so list_transactions + undo_transaction can back it out.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dropYesHandle or gramps_id of the object absorbed into it.
keepYesHandle or gramps_id of the object that SURVIVES.
dry_runNoTrue (default) reports what would move without changing anything. Set False to apply.
enclosuresNoPlaces only: the survivor otherwise gets both places' parents. 'auto' drops an undated parent that encloses another (a state beside its county) and refuses if two unrelated undated parents remain; or 'keep_keeper', 'keep_drop', 'keep_both'. Dated enclosures are always kept.auto
object_typeYesperson, family, event, place, source, citation, repository, media, or note.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.1
    • addedInput schema / properties / enclosures
      Added value: +{
+  "default": "auto",
+  "description": "Places only: the survivor otherwise gets both places' parents. 'auto' drops an undated parent that encloses another (a state beside its county) and refuses if two unrelated undated parents remain; or 'keep_keeper', 'keep_drop', 'keep_both'. Dated enclosures are always kept.",
+  "type": "string"
+}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already carry the safety profile (destructive=true, readOnly=false, idempotent=false), and the description adds substantial context beyond it: dry-run is on by default, the whole merge is a single transaction so it is reversible via undo_transaction, and a botched manual merge can silently lose data held in the dropped object's subordinate lists. This is exactly the 'what gets destroyed and how to recover' context the annotations cannot express.

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?

Purpose and the dry-run default are front-loaded, which is the right ordering for a destructive tool. The middle paragraph on citations is long and slightly editorial, but it is the paragraph that supplies the crucial when-not guidance, so only a little is wasted.

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 merge with no output schema, the description covers what an agent needs: safety (dry-run default), reversibility (single transaction + undo), blast radius (all references repointed, lists unioned), and the decision criteria for whether a merge is appropriate at all. Remaining details (enclosures enum, accepted object_type strings) are fully documented in the schema.

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 3 is the baseline. The description still adds value by explaining the asymmetry of keep/drop in terms of effects ('every reference to `drop` is re-pointed at `keep`'), which sharpens the schema's terser 'SURVIVES'/'absorbed into it'. The enclosures parameter's auto/refusal behavior is left entirely to the schema, so it does not reach a 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?

States a specific verb and resource ('Merge two objects that are the same thing') and immediately distinguishes itself from the sibling threats: find_duplicates only finds, delete_object removes, while this is a server-side merge. It also names the mechanism (references to `drop` re-pointed at `keep`, subordinate lists unioned in one transaction), so an agent knows exactly 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.

Usage Guidelines5/5

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

It gives explicit when-not guidance with a concrete domain example (an index entry and the register page it indexes are two documents and must stay separate) and the converse case (the same census page entered per household member IS one document). It also points to the recovery path (list_transactions + undo_transaction) and flags the dry-run default as the safe entry point.

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