Gramps Web MCP

Overview Schema Source Related Servers Discussions Admin

Update Family

update_family

DestructiveIdempotent

Instructions

Change an existing family's father, mother, relationship type, children, family events, attributes or links to citations, notes, media and tags. For a new family use create_family; to remove one, delete_object. To add one child, pass it in childRefs with linkMode add; in replace mode childRefs must hold every child the family keeps. attributes replace the whole list whatever linkMode says, and sort reorders children, events, citations or media by date without changing which are linked. Pass only what changes; omitted arguments stay as they are. Link lists (…Handles, …Refs) follow linkMode: replace (default) sets the whole list, add appends, remove drops the given handles; in replace mode [] REMOVES every link of that kind, though the linked records themselves stay in the tree. Gramps Web keeps the people's side in step in the same save: a new father, mother or child gets the family on their record, and one replaced or removed loses it; a father, mother or new child that does not exist makes it refuse the change, and nothing is saved. Returns a short header with the type, action updated, handle and Gramps ID, not the changed family: read it back with get_object. A missing family returns a not-found message. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it. Formats of every argument: get_reference(topic: "input-guide").

Input Schema

Name	Required	Description	Default
`sort`	No	Lists to put in date order after the other changes: JSON array ["Events","Citations"] or one string such as "Events \| Citations"; names are case-insensitive. Links are only moved, keeping their roles and other metadata; alone it sorts the stored lists. Omit to keep the order (linkMode add appends at the end). Lists: Events, Children, Citations, Media. Events: by event date; undated Birth, Baptism and Christening go first and other undated events last, ending with Death, then Burial and Cremation. On the same date: "before" dates, then Residence and Occupation, Birth, Baptism, other events, Death, Burial, then "after" dates. Children: by birth date, else baptism or christening date. Citations and Media: by their own date. Undated children, citations and media go last; equal dates keep their order.
`handle`	Yes	The family to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
`linkMode`	No	How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata.	replace
`childRefs`	No	Children with their relations to the parents. In replace mode the list must hold every child the family keeps. Omit to keep; applied per linkMode. Child references (handles, not Gramps IDs): JSON array of {ref, frel, mrel}, strings "HANDLE::RelType" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. A relation must be a standard Gramps one (Birth, Adopted, Stepchild, Sponsored, Foster, Unknown, None) or a custom one the tree already uses. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.).
`eventRefs`	No	Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings "HANDLE::Role" (default role: Primary on a person, Family on a family), comma/pipe/newline-separated, or a single handle. A role must be a standard Gramps role or a custom one the tree already uses; anything else is rejected with suggestions. JSON objects accept snake_case or camelCase list fields (note_list / noteList).
`isPrivate`	No	true makes the record private, false public. Omit to leave unchanged.
`attributes`	No	Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or \| between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide.
`tagHandles`	No	Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
`noteHandles`	No	Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
`fatherHandle`	No	New father. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
`mediaHandles`	No	Media. Omit to keep; applied per linkMode. Media handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string. To show only part of an image, such as one record on a page scan, give an object {"ref":"…","region":[left, top, right, bottom]} in place of the handle. A region is [left, top, right, bottom]: its edges in percent of the image width and height, 0 to 100, measured from the top-left corner; [10, 20, 60, 45] runs from 10% to 60% across and from 20% to 45% down. [0, 0, 100, 100] shows the whole image again; read_media with the same region shows what it covers. A plain handle keeps the region its link has. In add mode a media already shown keeps its link and takes the region given; to show two regions of one image, list it twice, each with its region.
`motherHandle`	No	New mother. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
`citationHandles`	No	Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
`relationshipType`	No	Relationship type (Married, Unmarried, Civil Union, Unknown). Omit to leave unchanged. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: "types").

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.8.1Nov 1, 2026

changedInput schema / properties / eventRefs / description

Previous value: -"Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings \"HANDLE::Role\" (default role: Primary), comma/pipe/newline-separated, or a single handle. A role must be a standard Gramps role or a custom one the tree already uses; anything else is rejected with suggestions. JSON objects accept snake_case or camelCase list fields (note_list / noteList)."New value: +"Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings \"HANDLE::Role\" (default role: Primary on a person, Family on a family), comma/pipe/newline-separated, or a single handle. A role must be a standard Gramps role or a custom one the tree already uses; anything else is rejected with suggestions. JSON objects accept snake_case or camelCase list fields (note_list / noteList)."

Changed3 schema fields changedv2.5.1Oct 15, 2026

changedInput schema / properties / mediaHandles / description

Previous value: -"Media. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."New value: +"Media. Omit to keep; applied per linkMode. Media handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string. To show only part of an image, such as one record on a page scan, give an object {\"ref\":\"…\",\"region\":[left, top, right, bottom]} in place of the handle. A region is [left, top, right, bottom]: its edges in percent of the image width and height, 0 to 100, measured from the top-left corner; [10, 20, 60, 45] runs from 10% to 60% across and from 20% to 45% down. [0, 0, 100, 100] shows the whole image again; read_media with the same region shows what it covers. A plain handle keeps the region its link has. In add mode a media already shown keeps its link and takes the region given; to show two regions of one image, list it twice, each with its region."

addedInput schema / properties / sort

Added value: +{
+  "default": null,
+  "description": "Lists to put in date order after the other changes: JSON array [\"Events\",\"Citations\"] or one string such as \"Events | Citations\"; names are case-insensitive. Links are only moved, keeping their roles and other metadata; alone it sorts the stored lists. Omit to keep the order (linkMode add appends at the end). Lists: Events, Children, Citations, Media. Events: by event date; undated Birth, Baptism and Christening go first and other undated events last, ending with Death, then Burial and Cremation. On the same date: \"before\" dates, then Residence and Occupation, Birth, Baptism, other events, Death, Burial, then \"after\" dates. Children: by birth date, else baptism or christening date. Citations and Media: by their own date. Undated children, citations and media go last; equal dates keep their order."
+}

removedInput schema / properties / sortEvents

Removed value: -{
-  "default": false,
-  "description": "true sorts all event links by event date after the other changes, keeping each link's role and metadata; alone it sorts the stored list. Undated Birth, Baptism and Christening go first and other undated events last, ending with Death, then Burial and Cremation. On the same date: \"before\" dates, then Residence and Occupation, Birth, Baptism, other events, Death, Burial, then \"after\" dates. Default false keeps the order (linkMode add appends at the end).",
-  "type": "boolean"
-}

Changed4 schema fields changedv2.3.2Oct 13, 2026

changedInput schema / properties / attributes / description

Previous value: -"Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings \"Type: Value\" (first colon), or one string with lines or | between entries. Full grammar: gramps://input-guide."New value: +"Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings \"Type: Value\" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide."

changedInput schema / properties / childRefs / description

Previous value: -"Children with their relations to the parents. In replace mode the list must hold every child the family keeps. Omit to keep; applied per linkMode. Child references (handles, not Gramps IDs): JSON array of {ref, frel, mrel}, strings \"HANDLE::RelType\" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.)."New value: +"Children with their relations to the parents. In replace mode the list must hold every child the family keeps. Omit to keep; applied per linkMode. Child references (handles, not Gramps IDs): JSON array of {ref, frel, mrel}, strings \"HANDLE::RelType\" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. A relation must be a standard Gramps one (Birth, Adopted, Stepchild, Sponsored, Foster, Unknown, None) or a custom one the tree already uses. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.)."

changedInput schema / properties / eventRefs / description

Previous value: -"Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings \"HANDLE::Role\" (default role: Primary), comma/pipe/newline-separated, or a single handle. JSON objects accept snake_case or camelCase list fields (note_list / noteList)."New value: +"Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings \"HANDLE::Role\" (default role: Primary), comma/pipe/newline-separated, or a single handle. A role must be a standard Gramps role or a custom one the tree already uses; anything else is rejected with suggestions. JSON objects accept snake_case or camelCase list fields (note_list / noteList)."

addedInput schema / properties / sortEvents

Added value: +{
+  "default": false,
+  "description": "true sorts all event links by event date after the other changes, keeping each link's role and metadata; alone it sorts the stored list. Undated Birth, Baptism and Christening go first and other undated events last, ending with Death, then Burial and Cremation. On the same date: \"before\" dates, then Residence and Occupation, Birth, Baptism, other events, Death, Burial, then \"after\" dates. Default false keeps the order (linkMode add appends at the end).",
+  "type": "boolean"
+}

Changed1 schema field changedv2.3.1Oct 7, 2026

changedInput schema / properties / linkMode / description

Previous value: -"How to apply all supplied link lists: replace (default) replaces each full list; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata."New value: +"How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata."

Changed12 schema fields changedv2.3.0Oct 6, 2026

changedInput schema / properties / attributes / description

Previous value: -"Replace attributes. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Attributes: JSON array of objects {type,value,...}, or strings \"Type: Value\" (first colon), or one string with lines or | between entries. Full grammar: gramps://input-guide."New value: +"Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings \"Type: Value\" (first colon), or one string with lines or | between entries. Full grammar: gramps://input-guide."

changedInput schema / properties / childRefs / description

Previous value: -"Linked all children. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Child references: JSON array of {ref, frel, mrel}, strings \"HANDLE::RelType\" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.)."New value: +"Children with their relations to the parents. In replace mode the list must hold every child the family keeps. Omit to keep; applied per linkMode. Child references (handles, not Gramps IDs): JSON array of {ref, frel, mrel}, strings \"HANDLE::RelType\" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.)."

changedInput schema / properties / citationHandles / description

Previous value: -"Linked citation links. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."

changedInput schema / properties / eventRefs / description

Previous value: -"Linked family–event links. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Event references: JSON array of {ref, role}, strings \"HANDLE::Role\" (default role: Primary), comma/pipe/newline-separated, or a single handle. JSON objects accept snake_case or camelCase list fields (note_list / noteList)."New value: +"Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings \"HANDLE::Role\" (default role: Primary), comma/pipe/newline-separated, or a single handle. JSON objects accept snake_case or camelCase list fields (note_list / noteList)."

changedInput schema / properties / fatherHandle / description

Previous value: -"Father person handle. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001). Handles are opaque strings from the API. Gramps IDs (like I0001, F0023) are auto-resolved to handles. Find handles with search() or list_objects()."New value: +"New father. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."

changedInput schema / properties / handle / description

Previous value: -"Family handle. Handle or Gramps ID (e.g. I0001). Handles are opaque strings from the API. Gramps IDs (like I0001, F0023) are auto-resolved to handles. Find handles with search() or list_objects()."New value: +"The family to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."

changedInput schema / properties / isPrivate / description

Previous value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged."

changedInput schema / properties / mediaHandles / description

Previous value: -"Linked media links. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Media. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."

changedInput schema / properties / motherHandle / description

Previous value: -"Mother person handle. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001). Handles are opaque strings from the API. Gramps IDs (like I0001, F0023) are auto-resolved to handles. Find handles with search() or list_objects()."New value: +"New mother. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."

changedInput schema / properties / noteHandles / description

Previous value: -"Linked note links. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."

changedInput schema / properties / relationshipType / description

Previous value: -"Relationship type string. Omit to leave unchanged. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values."New value: +"Relationship type (Married, Unmarried, Civil Union, Unknown). Omit to leave unchanged. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: \"types\")."

changedInput schema / properties / tagHandles / description

Previous value: -"Linked tag links. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."

First observedv2.2.0Oct 3, 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=true, but the description adds substantial behavior beyond them: Gramps Web updates the people's reciprocal records in the same save, a nonexistent father/mother/child aborts the entire change with nothing saved, writes are serialized and require tree-edit permission, and locked or rate-limited writes report a retry delay. It also discloses that the return value is only a short header rather than the changed object, directing the caller to get_object.

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 description is long but front-loaded: purpose first, then alternatives, then linkMode rules, then side effects and return behavior. Nearly every sentence carries non-obvious operational information, though a few points (linkMode semantics, attributes replacing regardless of linkMode) are restated from the schema descriptions and could be trimmed.

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?

There is no output schema, yet the description states exactly what comes back (type, action, handle, Gramps ID) and how to retrieve the changed family, and it covers missing-handle and rate-limit failure modes. For a destructive, 14-parameter mutation tool, nothing an agent needs in order to invoke it safely 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 coverage is 100%, so the schema carries the per-parameter detail and the baseline is 3. The description still adds cross-parameter semantics the schema cannot easily express: linkMode governs all handle/ref lists uniformly, [] in replace mode removes every link of that kind without deleting the linked records, attributes always replace regardless of linkMode, and sort reorders without changing membership.

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 names a specific verb and resource ('Change an existing family's') and enumerates the mutable facets: father, mother, relationship type, children, events, attributes and link lists. It immediately distinguishes itself from create_family and delete_object, so an agent can route without consulting the schema.

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 and when-not-to-use guidance by naming create_family and delete_object as alternatives, and it explains the linkMode choice (replace default, add appends, remove drops) plus the special rule that attributes always replace. The 'pass only what changes; omitted arguments stay as they are' sentence resolves the main ambiguity for a 14-parameter update tool.

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

Update Family

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools