gramps-evidence-mcp

Overview Schema Source Related Servers Discussions Admin

add_family

Create a family record linking existing parents and children, with an optional cited marriage event. Build family units after individuals are added.

Instructions

Create a family linking parents and children, with an optional cited marriage.

All members must already exist (create them first with add_person). Creating the family automatically links each person's family/parent-family lists, so you don't need to update the individuals separately. Cite the marriage event to a marriage record where possible.

Input Schema

Name	Required	Description	Default
`father`	No	Father: handle or gramps_id.
`mother`	No	Mother: handle or gramps_id.
`children`	No	Children: handles or gramps_ids, each a birth child of both parents, or {person, frel, mrel} for a stepchild, adopted or foster child.
`marriage`	No	Optional marriage event; type defaults to 'Marriage'. Cite it.
`relationship`	No	Family relationship type, e.g. 'Married', 'Unmarried', 'Civil Union'.	Married
`allow_new_type`	No	Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names.
`require_citation`	No	Require a citation on the marriage event (default).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.3.0Oct 16, 2026

addedInput schema / $defs / ChildLink

Added value: +{
+  "additionalProperties": false,
+  "description": "One child of add_family, with its relationship to each parent.",
+  "properties": {
+    "frel": {
+      "default": "Birth",
+      "description": "Relationship to the father: 'Birth', 'Adopted', 'Stepchild', 'Foster', ...",
+      "type": "string"
+    },
+    "mrel": {
+      "default": "Birth",
+      "description": "Relationship to the mother, the same values.",
+      "type": "string"
+    },
+    "person": {
+      "description": "The child's handle or gramps_id, e.g. 'I0007'.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "person"
+  ],
+  "type": "object"
+}

changedInput schema / properties / children / anyOf

Previous value: -[
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "$ref": "#/$defs/ChildLink"
+        }
+      ]
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / children / description

Previous value: -"Child handles or gramps_ids."New value: +"Children: handles or gramps_ids, each a birth child of both parents, or {person, frel, mrel} for a stepchild, adopted or foster child."

Changed4 schema fields changedv1.2.0Oct 5, 2026

removedInput schema / $defs / EventInput

Removed value: -{
-  "additionalProperties": false,
-  "description": "A dated/placed fact about a person or family.",
-  "properties": {
-    "citation": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/CitationInput"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Citation supporting this event (see require_citation)."
-    },
-    "date": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Date, Gramps style: '1899', '12 JAN 1899', 'ABT 1900', 'BEF 1950'; 'BET 1898 AND 1901' happened once within the range; 'FROM 1864 TO 1865' lasted the whole span; 'FROM 1880' or 'TO 1890' is open at one end."
-    },
-    "description": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Free-text description."
-    },
-    "place": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Place reference. Resolved in order: existing handle/gramps_id, exact title ('Columbus, Ohio, USA'), then exact unique name ('Columbus' — errors if several places share it); only a string matching nothing creates a new place. Prefer the gramps_id or full title of an existing place."
-    },
-    "type": {
-      "description": "Gramps event type, e.g. 'Birth', 'Death', 'Marriage', 'Baptism', 'Burial', 'Residence', 'Occupation', 'Census'.",
-      "type": "string"
-    }
-  },
-  "required": [
-    "type"
-  ],
-  "type": "object"
-}

addedInput schema / $defs / VitalEventInput

Added value: +{
+  "additionalProperties": false,
+  "description": "A birth, death or marriage given with the person or family it belongs to.\n\nThe parameter already names the event, so its type may be left out;\n``add_person`` and ``add_family`` fill it in.",
+  "properties": {
+    "allow_new_type": {
+      "default": false,
+      "description": "Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names.",
+      "type": "boolean"
+    },
+    "citation": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/CitationInput"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Citation supporting this event (see require_citation)."
+    },
+    "date": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Date, Gramps style: '1899', '12 JAN 1899', 'ABT 1900', 'BEF 1950'; 'BET 1898 AND 1901' happened once within the range; 'FROM 1864 TO 1865' lasted the whole span; 'FROM 1880' or 'TO 1890' is open at one end."
+    },
+    "description": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Free-text description."
+    },
+    "place": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Place reference. Resolved in order: existing handle/gramps_id, exact title ('Columbus, Ohio, USA'), then exact unique name ('Columbus' — errors if several places share it); only a string matching nothing creates a new place. Prefer the gramps_id or full title of an existing place."
+    },
+    "type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Leave out: the parameter names the event (Birth, Death or Marriage)."
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / allow_new_type

Added value: +{
+  "default": false,
+  "description": "Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names.",
+  "type": "boolean"
+}

changedInput schema / properties / marriage / anyOf

Previous value: -[
-  {
-    "$ref": "#/$defs/EventInput"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "$ref": "#/$defs/VitalEventInput"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedv1.0.1Oct 1, 2026

changedInput schema / $defs / EventInput / properties / date / description

Previous value: -"Date, free text in Gramps style: '1899', '12 JAN 1899', 'ABT 1900', 'BET 1898 AND 1901', 'BEF 1950'."New value: +"Date, Gramps style: '1899', '12 JAN 1899', 'ABT 1900', 'BEF 1950'; 'BET 1898 AND 1901' happened once within the range; 'FROM 1864 TO 1865' lasted the whole span; 'FROM 1880' or 'TO 1890' is open at one end."

First observedv0.1.0Sep 29, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds real behavioral context beyond that: the side effect that family/parent-family lists on each person are linked automatically, the prerequisite that referenced people must exist, and the citation expectation for the marriage.

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?

Front-loaded with the core action, then prerequisites, then the auto-linking side effect and citation advice. Four sentences, each carrying distinct information; only the closing citation sentence overlaps mildly with the schema's 'Cite it.'

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

Completeness4/5

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

For a write tool with no output schema and a rich 7-parameter schema, the description covers the prerequisite, the auto-linking behavior, and citation guidance. It could say more about what is returned or about idempotency/re-run behavior, but nothing an agent needs to invoke it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter (father, mother, children, marriage, relationship, allow_new_type, require_citation) is already documented in the schema, including the ChildLink frel/mrel and CitationInput precedence. The description mentions marriage citation but adds no syntax or format meaning beyond what the schema provides, so the baseline 3 applies.

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 ('Create a family linking parents and children') plus the optional cited marriage, so the agent can distinguish it from add_person and the granular family-mutation siblings (add_child_to_family, set_family_parent). The scope of what the tool produces is unambiguous.

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?

Gives a clear prerequisite ('All members must already exist (create them first with add_person)') and tells the agent when citing is warranted ('Cite the marriage event to a marriage record where possible'). It does not, however, address when to prefer this tool over the granular siblings like add_child_to_family or move_child.

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

Deploy Server

add_family

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools