Skip to main content
Glama
Sign In
Scormave

Gramps Web MCP

by Scormave
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Merge Objects

merge_objects
DestructiveIdempotent

Merge a confirmed duplicate record into the record to keep, moving its details and links in one transaction and deleting the duplicate. Use only after verifying both records describe the same entity.

Instructions

Merge a duplicate into the record to keep when both describe the same person, family, event, place, source, citation, note, media object or repository: Gramps Web moves the duplicate's details and every link to it onto the kept record and deletes the duplicate, all in one transaction. Call it only after the user confirmed that the two records are the same; read both with get_object first, and find candidates with search or list_objects. The kept record keeps its own fields: a person's primary name, gender, birth and death, an event's type, date, place and description, a source's title, a citation's page, date and source, a note's text, a media object's file. The duplicate's name becomes an alternate name of the kept person or place, and its events, children, parents, notes, citations, media, attributes and tags are added. Merging two people also merges a family the duplicate had with the same partner (mergeFamilies); merging two families merges their different fathers into one person and their different mothers into one person. Gramps refuses to merge spouses or a parent with their child, and tags cannot be merged. Clients that support it show the user a confirmation dialog first; action declined or cancelled means nothing changed. Returns action merged with the kept and deleted records and the transaction number: undo_change with it restores the duplicate.

Input Schema

NameRequiredDescriptionDefault
keepHandleYesThe record that stays and keeps its own fields. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
objectTypeYesType of both records: person, family, event, place, source, citation, note, media or repository.
fatherHandleNoFamilies only: the father who stays when the two families name different fathers, who then become one person. The father of either family; default is the kept family's father, or the duplicate's when the kept family has none.
motherHandleNoFamilies only: the mother who stays when the two families name different mothers, who then become one person. The mother of either family; default is the kept family's mother, or the duplicate's when the kept family has none.
mergeFamiliesNoPeople only: true (default) also merges a family the duplicate had with the same partner as one of the kept person's families; false keeps both families. Ignored for other types.
duplicateHandleYesThe duplicate: its details and links move to the kept record, then it is deleted. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.9.1

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the destructiveHint and idempotentHint annotations, the description explains exactly what is moved, what is kept, what is deleted, and that the operation occurs in one transaction. It further discloses family-merge nuances, refusal cases, confirmation-dialog behavior, and how undo_change can restore the deleted duplicate.

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

Conciseness5/5

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

The description is dense but front-loaded, starting with the core action and scope before moving into prerequisites, behavioral details, and return values. Despite its length, every sentence carries operational information relevant to a destructive merge tool.

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, multi-type merge operation with no output schema, the description covers purpose, prerequisites, edge cases, return shape, and undo behavior. An agent has enough information to decide when to call it and what to expect.

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, but the description adds useful semantic context: keepHandle and duplicateHandle are tied to which record keeps its fields versus which is moved and deleted, and mergeFamilies/fatherHandle/motherHandle behavior is elaborated. It stops short of adding new parameter-specific syntax or constraints beyond the schema.

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 states a specific verb and resource: merge a duplicate into the record to keep, with an explicit list of supported Gramps object types. It clearly distinguishes this operation from update/delete siblings by describing the one-transaction move-and-delete behavior.

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-to-use guidance: only after user confirmation that the records are the same, after reading both with get_object, and after finding candidates with search or list_objects. It also names conditions where merging is refused, such as spouses or parent-child pairs, and notes that tags cannot be merged.

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