genealogy-mcp

Overview Schema Source Related Servers Discussions Admin

project_save

Instructions

Add or change a person, family, source or research lead in the project. Every change of an existing record is logged with the old and new value, the reason and the documents. Save the source first, then cite its S-id. In a gene-archive site folder the change goes through gene apply: refused if it adds an error, logged, committed to git under the owner's name, and the site is rebuilt. In a .ged file only the changed lines are rewritten (everything else in the file stays as it was), a copy is kept, and gedcom_changes shows the lines. Ask the user before writing into their archive or tree.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project": "<project>",
      "kind": "<kind>",
      "record": "<record>"
    },
    "name": "project_save"
  }
}

Input Schema

Name	Required	Description
`kind`	Yes
`delete`	No
`reason`	No	Why this was added or changed — kept in the corrections log
`record`	Yes	Fields. person: given_names, surname, sex (M/F), birth/death/burial {date, place_as_recorded, source_ids, note}, notes, research_status ('confirmed' \| 'probable' \| 'unlinked_candidate'). family: partners [ids], children [ids], marriage {date, place_as_recorded, source_ids}, source_ids. source: title, kind (parish_register, census, military, civil_record, family_document, photo, book, web…), locator (archive, fond, opis, delo, folio — or film/image), url, scope (what it says: transcription). lead: title, record (where), person_id, url, next (required specific next step), checked (ISO date or null), status (open\|active\|waiting_owner\|reading_room\|closed), blocked_by (owner task/missing document), resolution, stage (family\|civil_registry\|existing_documents\|primary_records\|secondary_sources), stage_result (required when advancing), expected_sources [source ids to check before advancing]. Pass "id" to update an existing record (a field set to null is removed).
`dry_run`	No	Check the change and show it without writing — use it to show the user what will be saved
`project`	Yes	Project name, the path of a gene-archive site folder, or the path of a .ged file
`source_ids`	No	Sources (S…) that prove it

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.7.0Oct 22, 2026

changedInput schema / properties / record / description

Previous value: -"Fields. person: given_names, surname, sex (M/F), birth/death/burial {date, place_as_recorded, source_ids, note}, notes, research_status ('confirmed' | 'probable' | 'unlinked_candidate').\nfamily: partners [ids], children [ids], marriage {date, place_as_recorded, source_ids}, source_ids.\nsource: title, kind (parish_register, census, military, civil_record, family_document, photo, book, web…), locator (archive, fond, opis, delo, folio — or film/image), url, scope (what it says: transcription).\nlead: title (what to check), record (where), person_id, url, status ('open'|'closed'), resolution.\nPass \"id\" to update an existing record (a field set to null is removed)."New value: +"Fields. person: given_names, surname, sex (M/F), birth/death/burial {date, place_as_recorded, source_ids, note}, notes, research_status ('confirmed' | 'probable' | 'unlinked_candidate').\nfamily: partners [ids], children [ids], marriage {date, place_as_recorded, source_ids}, source_ids.\nsource: title, kind (parish_register, census, military, civil_record, family_document, photo, book, web…), locator (archive, fond, opis, delo, folio — or film/image), url, scope (what it says: transcription).\nlead: title, record (where), person_id, url, next (required specific next step), checked (ISO date or null),\nstatus (open|active|waiting_owner|reading_room|closed), blocked_by (owner task/missing document), resolution,\nstage (family|civil_registry|existing_documents|primary_records|secondary_sources), stage_result (required when advancing), expected_sources [source ids to check before advancing].\nPass \"id\" to update an existing record (a field set to null is removed)."

First observedv0.5.1Oct 16, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: changes to existing records are logged with old/new value, reason and documents; in a site folder the write runs through `gene apply`, is refused on validation error, git-committed under the owner's name and triggers a rebuild; in a .ged only changed lines are rewritten and a backup copy is kept. That is exactly the write-side context an agent needs and cannot get from readOnlyHint/destructiveHint alone.

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-loads the core action and then branches into the two execution modes, so structure matches how an agent reasons about the call. It is dense but every clause carries operational meaning; only the site-folder `gene apply` sentence is heavy enough to slow scanning.

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?

Covers both target types, the logging/backup guarantees, and the human-in-the-loop requirement, and an output schema exists so return values need not be explained. What's missing is any note on the delete/field-removal path and on what happens when validation refuses the write (beyond 'refused if it adds an error').

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 71%, so the schema already carries most per-field detail (record shapes, dry_run, project paths). The description still adds meaning the schema does not: the ordering requirement to create the source first and then cite its S-id, and that the `reason` value is what lands in the corrections log. The `delete` flag is not discussed in the description at all.

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 ('Add or change a person, family, source or research lead in the project') and enumerates the record kinds, which maps directly to the `kind` enum. It is plainly distinguishable from read-oriented siblings such as project_view, project_log and project_evidence.

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 concrete sequencing guidance ('Save the source first, then cite its S-id') and a consent rule ('Ask the user before writing into their archive or tree'). It lacks an explicit statement of when to prefer a sibling tool (e.g. project_transfer for moving data), so it falls short of a full when/when-not pair.

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