Skip to main content
Glama
Sign In
Scormave

Gramps Web MCP

by Scormave
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Create Records

create_records

Create many linked genealogy records in one atomic transaction—people, families, events, places, sources, citations, notes and repositories—and link them together by #key.

Instructions

Create many linked records in one call: repositories, places, sources, notes, citations, events, people and families. Gramps Web saves them in one transaction, so either all are created or none, and undo_change on that transaction (get_recent_changes) removes them all again. Give a record that others link to a key and write "#key" wherever a handle is taken: a citation's sourceHandle "#src", an event's citationHandles ["#cit"], a person's eventRefs ["#birth"], a family's fatherHandle "#ivan" and childRefs ["#petr"]. Existing records are linked by handle, or by Gramps ID where the create tool accepts one. Each record takes the arguments of its create tool (create_person, create_event, …), except that people join families only through families: a new family's father, mother and children get the link back. Links from existing records to new ones, such as a new child of an existing family, are made afterwards with update_* and linkMode "add". Media and tags are not created here: create them first with create_media and create_tag. Each new person is checked for duplicates in the tree as in create_person: a possible duplicate stops the whole call with action "refused", and notDuplicateOf on that person lets it through; other record types are not checked, so search first. Up to 50 records per call; every record is checked before anything is saved, and an error names the record, e.g. people[1]. Returns each record's handle and Gramps ID. 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

NameRequiredDescriptionDefault
notesNoNew notes; fields as in create_note. Other records link them through noteHandles.
eventsNoNew events; fields as in create_event. People and families link them through eventRefs.
peopleNoNew people; fields as in create_person, without familyHandles and parentFamilyHandles: name a person in a family's fatherHandle, motherHandle or childRefs instead.
placesNoNew places; fields as in create_place. enclosedBy may name a place of this call by "#key".
sourcesNoNew sources; fields as in create_source.
familiesNoNew families; fields as in create_family. They are saved after the people, which get the link back.
citationsNoNew citations; fields as in create_citation. Other records link them through citationHandles.
repositoriesNoNew repositories; fields as in create_repository.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.9.1
    • addedInput schema / properties / people / items / properties / notDuplicateOf
      Added value: +{
+  "description": "People of the tree who are someone else, from the possible duplicates of a refused call: Gramps IDs or handles, e.g. [\"I0012\"]. The duplicate check passes over them."
+}
  2. Changed2 schema fields changedv2.8.1
    • changedInput schema / properties / families / items / properties / eventRefs / description
      Previous value: -"Family events such as Marriage: handles or #keys, optionally \"#key::Family\" or {ref, role}."New value: +"Family events such as Marriage: handles or #keys, each optionally with a role as \"#key::Role\" or {ref, role} (default Family)."
    • changedInput schema / properties / families / items / properties / relationshipType / description
      Previous value: -"Married (default), Unmarried, Civil Union or Unknown."New value: +"Married, Unmarried, Civil Union or Unknown (default, as in Gramps). Pass Married when a source records the marriage."
  3. Addedv2.8.0

TDQS

A4.6/5.0
Behavior4/5

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

Beyond the annotations, it discloses transaction atomicity ('either all are created or none'), undo via undo_change/get_recent_changes, the duplicate-refusal behavior with the notDuplicateOf escape hatch, the 50-record cap, pre-save validation with path-style error names ('people[1]'), per-record sequential writes, and account/rate-limit requirements. This is unusually rich behavioral context; the only minor gap is that return-value shape is hinted ('each record's handle and Gramps ID') but not fully detailed, which is acceptable given the volume of other disclosure.

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 content is front-loaded with the core verb and transaction semantics, and nearly every sentence carries needed information. It is a dense single paragraph, however, and the linking convention is explained at length; breaking it into shorter logical blocks would improve scannability without losing content.

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 an 8-parameter batch tool with no output schema, the description covers atomicity, limits, error semantics, duplicate handling, linking rules, prerequisites for media/tags, and authentication/rate-limit behavior. Nothing an agent needs to invoke it correctly appears to be 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 baseline is 3. The description goes further by explaining the cross-record linking model holistically with concrete examples (a citation's sourceHandle "#src", a family's fatherHandle "#ivan"), and by clarifying that people join families only through families rather than familyHandles. That adds meaning beyond the per-field schema descriptions.

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 resource set: 'Create many linked records in one call: repositories, places, sources, notes, citations, events, people and families.' It clearly distinguishes the batch tool from the sibling create_* tools and from update_* by framing this as the single-call multi-record creator.

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 explicitly states when not to use it ('Media and tags are not created here: create them first with create_media and create_tag') and when to use alternatives ('Links from existing records to new ones ... are made afterwards with update_* and linkMode "add"'). It also tells the agent to search first for non-person records because only people are duplicate-checked.

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