Skip to main content
Glama

gramps-web-mcp

License: AGPL v3 .NET 10 MCP server version CI Docker on GHCR

WARNING

Update to 2.3.1 or later. Before 2.3.1 the update_* tools could drop stored data that the call did not mention (#5). If you edited a tree with an earlier version, check it for dropped data.

Companion MCP server for the Gramps Web open-source genealogy platform. It gives AI agents structured, tool-based access to family trees through the Model Context Protocol.

This project is not a standalone genealogy UI or replacement for Gramps Web. Run it alongside an existing Gramps Web instance; your users, trees, media, permissions, and genealogy editing UI stay in Gramps Web.

Features

  • Up to 29 MCP tools — read, create, update, and delete people, families, events, places, sources, citations, notes, media, repositories, and tags

  • Search and browse — full-text search and paginated object listing

  • Kinship tools — ancestors, descendants, relationships, and timelines

  • Incremental links — add or remove one event, child, citation, or note with linkMode, keeping every other link

  • Dates as Gramps writes them — ranges, before/after/about, and every Gramps calendar (1856-07-20 (Julian)), stored with the sort value Gramps computes

  • 6 MCP resources — type vocabularies, input guide, tree metadata, name settings, and opt-in media previews/files for vision-capable agents

  • Media safeguards — size limits, private-record defaults, and previews with EXIF/GPS metadata stripped

  • MCP prompts — guided workflows for research, finding connections, adding people/families, imports, changing links, and citing facts

  • Multiple transports — stdio (local clients), Streamable HTTP, legacy SSE

  • Read-only mode — publish only read tools and block direct mutation calls

See the tool catalog for the full list. Upgrading from 1.x? Follow the 2.0 migration guide to update saved tool calls and client settings.

All outgoing requests to Gramps Web, including authentication, media downloads, and health checks, automatically identify this application with User-Agent: gramps-web-mcp/<version> (+https://github.com/Scormave/gramps-web-mcp). The version comes from the application build; no configuration is required.

Related MCP server: ASPNET Core Debugging MCP Server

Prerequisites

  • .NET 10 SDK (for local development)

  • A running Gramps Web instance with API access

  • Docker (optional, for container deployment)

Quick start

Local development (demo server)

run-local-server.sh connects to the public demo.grampsweb.org instance using well-known demo credentials (owner / owner):

./run-local-server.sh

The server starts with HTTP transport at http://127.0.0.1:8080/mcp. No API key is required when binding to loopback only.

Docker

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry. Docker picks the matching architecture automatically; amd64 covers most Unraid and x86 hosts, arm64 covers Apple Silicon and ARM SBCs:

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

For refresh-token authentication, replace the GRAMPS_USERNAME and GRAMPS_PASSWORD lines with -e GRAMPS_REFRESH_TOKEN=your-refresh-token.

The image exposes a GET /health endpoint for Docker HEALTHCHECK, Unraid container health, and other uptime monitors. It returns HTTP 200 when the MCP server can authenticate against Gramps Web, or HTTP 503 otherwise. Probes reuse the token the tools use, so they do not log in to Gramps Web each time. The public response is minimal: { "status": "healthy" } or { "status": "unhealthy" }. Startup logs include a line such as Connected to Gramps Web at … once the API is reachable.

The image defaults to Streamable HTTP (MCP_TRANSPORT=http) on port 8080, which is what the commands above use. Clients that spawn the container themselves (such as MCP Registry installs) instead run it over stdio with -e MCP_TRANSPORT=stdio and stdin kept open (docker run -i); that is the mode declared in server.json.

For read-only mode, add -e GRAMPS_READ_ONLY=true:

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Unraid installation

Unraid users can install gramps-web-mcp from Community Applications. The template source is maintained at Scormave/gramps-web-mcp-unraid. For Unraid-specific help, see the support thread on the Unraid forums.

Basic setup:

  1. In Unraid, open Apps / Community Applications.

  2. Search for gramps-web-mcp and install the template.

  3. Set GRAMPS_API_URL, GRAMPS_TREE_ID, and either GRAMPS_USERNAME plus GRAMPS_PASSWORD or GRAMPS_REFRESH_TOKEN for your Gramps Web instance. Set MCP_API_KEY when the MCP port is reachable from other machines on your network.

  4. Keep the default container port 8080, or map it to another host port.

  5. Start the container and check /health; it returns HTTP 200 once the service can authenticate to Gramps Web, with a minimal JSON response.

For the easiest pairing, run Gramps Web and gramps-web-mcp on the same Unraid Docker network and set GRAMPS_API_URL to the Gramps Web container URL. The MCP endpoint for clients is http://<unraid-host>:<mapped-port>/mcp.

Gramps Web + MCP (Docker Compose)

To run Gramps Web and the MCP server on the same host and Docker network, use docker-compose.example.yml as a starting point:

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set an authentication method in .env
docker compose up -d

Gramps Web is published on port 5055; MCP is on 8080 (/mcp and /health). Inside the compose network the MCP container reaches Gramps Web at http://grampsweb:5000.

Claude Desktop (MCPB extension)

One-click install for Claude Desktop is available as an MCP Bundle (.mcpb) from GitHub Releases. Download the bundle for your platform:

Platform

Artifact

macOS Apple Silicon

gramps-web-mcp-claude-desktop-osx-arm64-v*.mcpb

macOS Intel

gramps-web-mcp-claude-desktop-osx-x64-v*.mcpb

Windows x64

gramps-web-mcp-claude-desktop-win-x64-v*.mcpb

Linux x64

gramps-web-mcp-claude-desktop-linux-x64-v*.mcpb

Linux ARM64

gramps-web-mcp-claude-desktop-linux-arm64-v*.mcpb

  1. Download the .mcpb file for your OS from the latest release.

  2. Double-click it, or drag it into the Claude Desktop window.

  3. Enter your Gramps Web URL, username, password/token, and tree UUID.

  4. Leave Read-only mode enabled for your first session; disable it only when you want Claude to create or edit records.

  5. Complete installation and start a new chat.

The extension runs locally over stdio and does not require the .NET SDK on your machine. See mcpb/README.md for packaging details and PRIVACY.md for the privacy policy.

To build a bundle locally:

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

MCP client configuration (manual)

stdio (e.g. Claude Desktop, Cursor):

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

To authenticate with a refresh token, omit GRAMPS_USERNAME and GRAMPS_PASSWORD from env and add "GRAMPS_REFRESH_TOKEN": "your-refresh-token" instead.

To run a stdio server in read-only mode, add "GRAMPS_READ_ONLY": "true" to env.

HTTP (remote / Docker):

Point your MCP client at http://host:8080/mcp with Streamable HTTP transport. When MCP_API_KEY is set, send it as Authorization: Bearer <key> or X-Api-Key: <key> on every MCP request.

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

Vision-capable agents can read opt-in media through read_media or through binary MCP resources such as gramps://media/{handle}/thumbnail/{size} and gramps://media/{handle}/file. read_media defaults to a thumbnail: a JPEG preview (PNG when the image has transparency) rendered by the server from the original, 1568 pixels on the long edge so handwriting and small print in document scans stay legible. Pass size (1–4096) for a smaller or larger preview; images are never upscaled. Previews are re-encoded from pixels, so EXIF (including GPS), XMP, IPTC, and ICC metadata are not sent. They can be rendered from JPEG, PNG, GIF, WebP, BMP, TIFF, TGA, PBM, and QOI originals; multi-page files use the first page. PDF and other non-image media, and AVIF, HEIC/HEIF, JPEG XL, and SVG images, have no preview. Use mode: "file" for an original file and omit size. File mode returns image, audio, or embedded blob resource content depending on MIME type; images that MCP clients cannot display, such as TIFF, come back as an embedded blob with a hint to use the thumbnail. End-to-end analysis depends on the MCP client forwarding the typed tool content or binary resource content to a capable model.

Configuration

Gramps connection

Variable

Description

GRAMPS_API_URL

Base URL of your Gramps Web instance (no trailing slash)

GRAMPS_USERNAME

API user name

GRAMPS_PASSWORD

API password

GRAMPS_TREE_ID

Tree UUID on that server

Refresh token instead of a password

If Gramps Web has password login turned off (OIDC_DISABLE_LOCAL_AUTH=true), set GRAMPS_REFRESH_TOKEN and leave GRAMPS_USERNAME and GRAMPS_PASSWORD unset. The server exchanges it for access tokens at /api/token/refresh/.

Get one while password login is still on:

curl -s -X POST https://gramps.example.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"mcp","password":"..."}' | jq -r .refresh_token

Gramps Web refresh tokens do not expire. Treat it like a password. Deleting the user or rotating the Gramps Web secret key invalidates it.

Runtime mode

Variable

Default

GRAMPS_READ_ONLY

false

GRAMPS_MUTATION_SERIALIZE

true

GRAMPS_MUTATION_MIN_INTERVAL_MS

0

  • GRAMPS_READ_ONLY: set to true to publish only read tools and block direct create, update, and delete calls.

  • GRAMPS_MUTATION_SERIALIZE: runs create/update/delete HTTP calls one at a time in this process. It also protects the complete read/modify/write sequence of update tools against other such calls in this process.

  • GRAMPS_MUTATION_MIN_INTERVAL_MS: minimum pause between mutation HTTP calls.

Runtime notes:

  • GRAMPS_READ_ONLY=false means the server starts in read/write mode.

  • The Claude Desktop MCPB extension is the exception: its setup form defaults to read-only for safer first use.

  • Write serialization and the optional interval protect typical Gramps Web SQLite trees from agent write bursts.

  • The write gate is in-process only. It does not coordinate across multiple MCP replicas, the Gramps Web UI, or other API clients.

  • SQLite deployments that still see database is locked on sequential edits should set GRAMPS_MUTATION_MIN_INTERVAL_MS=250 or 500.

  • On SQLite lock errors or upstream HTTP 429, mutation tools return a retryable MCP error with a short backoff hint instead of a generic 500.

  • Set GRAMPS_MUTATION_SERIALIZE=false when Gramps Web uses PostgreSQL and you want parallel writes.

Updating linked records

The nine update_* tools that accept link lists have a linkMode argument: replace (default), add, or remove. For example, update_person(handle: "PERSON_HANDLE", noteHandles: ["NOTE_HANDLE"], linkMode: "add") adds a note without copying the person's existing note list. remove takes the handles to unlink. An omitted list remains unchanged; [] clears a list only in replace mode. The mode applies to every supplied link list in the call. Existing link metadata is preserved by add; use replace to change that metadata. See the tool catalog for supported lists and concurrency limits.

Data dropped by updates before 2.3.1

Before 2.3.1 the update_* tools could drop stored data the call did not mention (#5). If you edited a tree with an earlier version, scripts/find-update-losses.py reads the Gramps Web transaction history and lists every value an update emptied, with the value it had and whether the record still lacks it:

GRAMPS_API_URL=https://gramps.example.com GRAMPS_USERNAME=me GRAMPS_PASSWORD=... \
  python3 scripts/find-update-losses.py --user MCP_ACCOUNT --until 2026-10-07 --json losses.json

It needs Python 3.9 or later and an account that may see private records, and it only reads. The history also holds edits made in the Gramps Web interface, and a value cleared on purpose looks the same as a dropped one, so check each finding before you restore it.

Media file access

Media byte tools/resources are disabled by default. get_object with objectType: "media" remains available for metadata without enabling file downloads. When disabled, read_media is omitted from tools/list; direct calls by a client that already knows its name return a configuration error without downloading bytes.

Variable

Description

Default

GRAMPS_MEDIA_RESOURCES_ENABLED

Enables binary media tools/resources for thumbnails and full files

false

GRAMPS_MEDIA_MAX_BYTES

Maximum bytes returned by read_media or any media resource

5242880

GRAMPS_MEDIA_ALLOW_PRIVATE

Allows bytes for Gramps media records marked private

false

Prefer read_media(mode: "thumbnail") or gramps://media/{handle}/thumbnail/{size} for AI analysis. Full files can be large and sensitive, carry their original metadata, and are still subject to the size and private-record checks.

GRAMPS_MEDIA_MAX_BYTES limits what is returned to the client. To render a thumbnail, the server downloads the original from Gramps Web into memory, up to 50 MiB or GRAMPS_MEDIA_MAX_BYTES, whichever is larger, and up to 100 megapixels; only the preview is returned.

GRAMPS_MEDIA_ALLOWED_MIME_TYPES is no longer used. Remove it from your configuration; the server ignores it and logs a warning at startup if it is set.

Transports

Set GRAMPS_API_URL, GRAMPS_TREE_ID, and either the username/password pair or GRAMPS_REFRESH_TOKEN as described above.

Value

Behavior

(unset or stdio)

JSON-RPC over stdin/stdout (default; local clients).

http

Streamable HTTP at MCP_PATH (default /mcp).

sse

Legacy MCP SSE: GET {MCP_PATH}/sse + POST {MCP_PATH}/message. Stateful; use for older clients only.

For HTTP transport, responses stream over SSE. See the Streamable HTTP spec for protocol details. Set ASPNETCORE_URLS to choose the listen address, for example http://127.0.0.1:8080.

Optional (MCP transport)

Variable

Description

Default

ASPNETCORE_URLS

Listen URLs for HTTP/SSE

—

MCP_PATH

URL prefix for MCP endpoints

/mcp

MCP_STATELESS

Stateless mode for Streamable HTTP

true

MCP_ENABLE_LEGACY_SSE

Expose legacy /sse with http transport

false

MCP_API_KEY

Shared secret for HTTP/SSE transport (comma-separated for rotation; min 16 characters)

—

HTTP authentication

When MCP_API_KEY is set, all MCP HTTP/SSE endpoints require the key on every request. GET /health stays anonymous for Docker and load-balancer probes.

Generate a key:

openssl rand -base64 32

Without a key, the server still starts (backward compatible). If the listen address is not loopback-only, a warning is logged recommending that you set MCP_API_KEY, use a reverse proxy with its own authentication, or bind to 127.0.0.1 for local use only.

Inside Docker, ASPNETCORE_URLS is typically http://0.0.0.0:8080, so the warning appears even when the host publishes the port on 127.0.0.1 only. That is expected when external access is already restricted.

Logging

Variable

Description

Default

GRAMPS_LOG_LEVEL

Log level for the server's own messages: Trace, Debug, Information, Warning, Error, Critical, None

Information

Logs go to stderr. Claude Desktop saves them to a local file (~/Library/Logs/Claude/mcp-server-Gramps Web MCP.log on macOS).

At Information, each Gramps API call is logged as its method, path (without the query string), status, duration, and body length; media downloads log the content type and length instead of the body length. Request and response bodies and full URLs hold genealogy data (names, dates, search terms), so they are logged only at Debug or Trace. Fields that look like credentials are redacted even then. Use Debug only while troubleshooting, and delete the log file afterwards.

Development

dotnet test

See CONTRIBUTING.md and the developer guide.

Documentation

Document

Description

docs index

All documentation files

Tool catalog

Complete MCP tool reference

Claude Desktop MCPB

Desktop extension packaging

Privacy policy

Data handling for the desktop extension

System prompt

Suggested prompt for MCP clients

Architecture

System design overview

Contributing

Contributions are welcome. See CONTRIBUTING.md.

Security

To report a vulnerability, see SECURITY.md.

Privacy Policy

The Claude Desktop extension is a local MCP server. It sends data only to the Gramps Web instance you configure and does not collect analytics or conversation data. See PRIVACY.md for full details.

License

Copyright (c) Scormave

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Because this is network server software, hosting a modified version requires making the corresponding source available to users interacting with it over a network.

Bundled third-party components, such as ImageSharp, the MCP C# SDK, and the .NET runtime, keep their own Apache 2.0 or MIT licenses; see THIRD-PARTY-NOTICES.txt. The MCP Bundles and the Docker image ship that file next to LICENSE.

Available Tools

29 tools
create_citationCreate Citation

Create a citation: one specific spot in an existing source (page, act or entry number) with its date, confidence, notes and media such as the scan. Returns the new handle, Gramps ID and page, with next steps. The source must already exist (search, or create_source). The citation supports nothing until it is attached: add it to each person, family, event or place it names (citationHandles, linkMode add, on their update tool). Does not check for duplicates; change an existing citation with update_citation. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoDate of the cited entry, optional. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected.
pageNoWhere in the source: page, act or entry number (optional). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text.
isPrivateNoMark the citation private (default false).
attributesNoAttributes: 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. Each attribute takes only type, value and private.
confidenceNoHow reliable the cited record is: Very Low, Low, Normal (default), High or Very High.Normal
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
noteHandlesNoNotes, e.g. a transcript of the entry (create_note with type Transcript). Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
mediaHandlesNoMedia such as the scan of the page. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
sourceHandleYesThe source being cited (required). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
create_eventCreate Event

Create a standalone event (Birth, Marriage, Residence, Census, …) with its date, place, description, citations, notes and media. Returns the new handle, Gramps ID and type, with next steps. The event is linked to nobody yet: attach it with update_person or update_family (eventRefs, linkMode add), which keeps their other events; several people can share one event, each with their own role. The place must exist: find it with search or create it with create_place. Change an existing event with update_event. An unknown type or unreadable date is rejected before anything is saved. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoWhen it happened, optional. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected.
eventTypeYesEvent type, e.g. Birth, Baptism, Death, Burial, Marriage, Residence, Occupation. 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").
isPrivateNoMark the event private (default false).
attributesNoAttributes: 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.
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
descriptionNoShort description, optional.
noteHandlesNoNotes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
placeHandleNoWhere it happened, optional; the place must exist (create_place). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
mediaHandlesNoMedia. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
citationHandlesNoCitations supporting the event. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
create_familyCreate Family

Create a family: a couple (father and mother, each optional) with their relationship type, children and family events such as Marriage. Returns the new handle, Gramps ID and a label, with next steps. People and events must already exist (create_person, create_event). Does not check for duplicates: look at the parents' families first, and change an existing family with update_family. Children are added here through childRefs, not through the child's parentFamilyHandles. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
childRefsNoChildren, each with its relation to the father and mother (Birth by default; Adopted, Stepchild, …). 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.).
eventRefsNoExisting family events such as Marriage or Divorce. 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).
isPrivateNoMark the family private (default false).
attributesNoAttributes: 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.
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
noteHandlesNoNotes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
fatherHandleNoThe father, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
mediaHandlesNoMedia. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
motherHandleNoThe mother, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
citationHandlesNoCitations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
relationshipTypeNoRelationship type: Married (default), Unmarried, Civil Union or Unknown. 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").Married
create_noteCreate NoteA

Create a free-text note (research notes, transcriptions, comments) of a given type. Returns the new handle, Gramps ID and type, with next steps. The note is attached to nothing yet: add its handle to the noteHandles of each person, family, event, place, source or citation it belongs to (their update tool, linkMode add). Change an existing note with update_note. An unknown type is rejected before anything is saved.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesThe note text (required).
formatNoText format: Plain (default) or Html.Plain
noteTypeNoNote type, default General; e.g. Research, Transcript, Person Note, Event Note, Citation. 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").General
isPrivateNoMark the note private (default false).
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false / destructiveHint=false; the description goes well beyond by disclosing the return payload (handle, Gramps ID, type), that the note starts unattached (a non-obvious post-condition), and that an unknown type is rejected before anything is saved (atomic failure semantics). That is real behavioral value not present in structured fields.

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 and return value, then the attachment workflow and the alternative tool. Dense but nearly every clause carries operational information; only the note-type rejection clause overlaps with the schema.

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 mutating create tool with no output schema, the description supplies the return shape, the unattached-state caveat, the linking follow-up, and failure behavior. Nothing an agent needs to call it correctly and handle the result 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 all five parameters are already documented including type validation and the get_reference(topic: "types") lookup. The description's note-type mention largely restates the schema, so the baseline 3 applies rather than a higher score.

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+resource ("Create a free-text note") plus the scope (research notes, transcriptions, comments) and the returned identifiers. It explicitly contrasts with the sibling update_note, so an agent can route between creation and editing without opening either 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?

Gives explicit when-to-use (new note), when-to-use-instead ("Change an existing note with update_note"), and the follow-up workflow: attach the returned handle to noteHandles of the owning person/family/event/place/source/citation via their update tool with linkMode add. Alternatives and prerequisites are both named.

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

create_personCreate Person

Create one person with full control: names, gender, links to existing events (with roles), families, citations, notes, media and tags, plus attributes, addresses, URLs and associations. Returns the new handle, Gramps ID and name, with next steps. Does not check for duplicates: search for the person first, and change an existing person with update_person. Events are separate records: create the Birth, Death and other events with create_event first and pass them in eventRefs, or attach them later with update_person (linkMode add). To make the person a child of a family, add them to the family's childRefs (create_family or update_family). Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
urlsNoURLs: JSON array of {type,path,desc}, or strings "Web Home: https://…" with optional " — note" after URL, or lines/| separated. A type must be a standard Gramps URL type (E-mail, Web Home, Web Search, FTP, Unknown) or a custom one the tree already uses. Grammar: gramps://input-guide.
genderNoGender: Female, Male, or Unknown (default Unknown).Unknown
addressesNoAddresses: JSON array of Gramps address objects; or text blocks with lines like street:, city:, … (blank line or --- between addresses); or one plain line = street only. Grammar: gramps://input-guide.
eventRefsNoExisting events this person takes part in, each with a role (Primary by default; Witness, Godparent, …). 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).
isPrivateNoMark the person private (default false).
attributesNoAttributes: 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.
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
noteHandlesNoNotes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
primaryNameYesName: full Gramps name JSON (see gramps://input-guide), a plain string ("Married Name:: Jane|Smith"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Name types and origins must be standard Gramps ones or custom ones the tree already uses. Plain full-name strings (name/text/full or "Given Middle Surname") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field.
mediaHandlesNoMedia. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
familyHandlesNoFamilies where this person is a parent or spouse. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
alternateNamesNoAlternate names: array of strings ("Married Name:: Jane|Smith"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). Name types and origins must be standard Gramps ones or custom ones the tree already uses. For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |).
citationHandlesNoCitations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
personAssociationsNoPerson associations (handles, not Gramps IDs): JSON array of {ref, rel, ...}, or strings "PERSON_HANDLE:: Godfather" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide.
parentFamilyHandlesNoFamilies where this person is a child. Does not add the person to the family's children: use childRefs on the family for that. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
create_placeCreate Place

Create a place (village, town, parish, county, country, …) with its name, type, coordinates, enclosing places, historical or other-language names, and links to notes, media, citations and tags. Returns the new handle and Gramps ID with the stored name, type, coordinates and enclosing places, and next steps. Does not check for duplicates: search for the place first, and change an existing one with update_place. Enclosing places must already exist: create the larger region first and pass it in enclosedBy, with dates when the place changed hands. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
latNoLatitude in decimal degrees, north positive (52.2297). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text.
lonNoLongitude in decimal degrees, east positive (21.0122). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text.
codeNoPlace code or postal code (optional).
nameYesPrimary name (required).
nameDateNoWhen the primary name applies (default: always). Gramps shows the first name, primary first, whose date is empty or matches the event date, so an undated primary name hides dated alternate names: date the primary name too ("from 1937-02-10"). Dashes are spans; open "1991-" / "from 1991" are From. Unreadable dates are rejected.
nameLangNoLanguage code of the primary name, e.g. pl or de (optional).
isPrivateNoMark the place private (default false).
placeTypeNoPlace type, e.g. Country, Province, County, City, Town, Village, Hamlet, Parish. 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").
enclosedByNoPlaces that contain this one. Parent place refs via enclosedBy (not enclosedByHandles): handle or Gramps ID, array of them, JSON array of {ref, date?}, or shorthand "HANDLE::1920-1950" (date optional). Place dashes are spans (from…to); open "1991-" / "from 1991" are From. English months OK: "HANDLE::from 1 Oct 1929 to 27 Sep 1937". Examples: [{ref:"…", date:"1708-1927"}], "HANDLE::1991-", date "1703-1914-08-31". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: "input-guide", section: "dates").
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
noteHandlesNoNotes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
mediaHandlesNoMedia. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
alternateNamesNoOther names: historical, other languages. Alternate place names: array of strings ("Old Name" or "Old Name::de"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:"New York", date:"1914-08-31-1924-01-26"}] or date "from 5 Jul 1944". Place dashes are spans (from…to); open "1991-" / "from 1991" are From. Unrecognized dates fail validation (see get_reference(topic: "input-guide", section: "dates")).
citationHandlesNoCitations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
create_repositoryCreate RepositoryA

Create a repository: an archive, library, church, website or other holder of sources. Returns the new handle, Gramps ID and name, with next steps. Does not check for duplicates: look through list_objects(objectType: "repositories") first so one holder is not entered twice; change an existing repository with update_repository. Link sources to it afterwards through repositoryHandles on create_source or update_source, which also carry the call number. noteHandles and tagHandles only link existing notes and tags (create_note, create_tag); nothing else is created or changed. An unknown type is rejected before anything is saved.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlNoWebsite, e.g. https://archive.example.org, stored as the repository's web home link (optional).
nameYesName, e.g. "State Archive in Warsaw" (required).
addressNoPostal address as one line, e.g. "12 High Street, London", stored as the street of the repository's address (optional).
repoTypeNoRepository type, e.g. Archive, Library, Church, Web site (optional; Gramps stores Library when omitted). 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").
isPrivateNoMark the repository private (default: false); Gramps Web hides private records from users not allowed to see them.
tagHandlesNoExisting tags to link (optional); create them first with create_tag. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
noteHandlesNoExisting notes to link (optional); create them first with create_note. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial behavior beyond that: no duplicate checking, unknown repoType rejected before anything is saved, noteHandles/tagHandles merely link existing records ('nothing else is created or changed'), and the exact return payload (handle, Gramps ID, name). That is well past the lowered bar set by the annotations.

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?

Four dense sentences, front-loaded with purpose and return value, then guarding constraints. Semicolons carry the subordinate details (duplicate risk, handle-only linking, validation) without filler, and no sentence is expendable.

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 mutation tool with no output schema, the description still supplies the return shape, the duplicate-detection limitation, the validation failure mode, and the downstream linking workflow. Nothing an agent needs to invoke it correctly is missing, and no output-schema explanation is owed.

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 is already documented with examples and defaults; the description's parameter content (type validation, handle-only linking) largely restates that. The only marginal addition is that create_source/update_source 'carry the call number' when linking, which concerns a sibling tool rather than this one's inputs.

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?

Opens with a specific verb and resource ('Create a repository') and immediately defines what a repository is ('an archive, library, church, website or other holder of sources'). It also names the create/update pair explicitly ('change an existing repository with update_repository'), so an agent can separate it from siblings like update_repository, create_source, or create_tag without opening a 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?

Gives explicit when-to-use and when-not-to-use instructions: check list_objects(objectType: "repositories") first because duplicates are not detected, use update_repository for existing holders, and attach sources afterwards via repositoryHandles on create_source/update_source. Alternative tools are named by name, not implied.

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

create_sourceCreate Source

Create a source: a book, register, archive unit or website that facts come from, with title, author, publication info and the repositories that hold it (with call numbers). Returns the new handle, Gramps ID and title, with next steps. Does not check for duplicates: search for the source first. A source alone proves nothing: cite a page or act of it with create_citation, then attach that citation to people and events. Change an existing source with update_source. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesTitle (required).
abbrevNoShort title for lists (optional).
authorNoAuthor or issuing body (optional).
pubinfoNoPublication info: publisher, place, year (optional).
isPrivateNoMark the source private (default false).
attributesNoAttributes: 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. Each attribute takes only type, value and private.
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
noteHandlesNoNotes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
mediaHandlesNoMedia. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.
repositoryHandlesNoRepositories that hold the source, each with an optional call number and media type; the repositories must exist (create_repository). Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings "Ref : CallNumber : MediaType". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: "Ref : CallNumber" and "Ref :: MediaType" are valid. MediaType must be a standard Gramps source media type (Book, Manuscript, Film, Photo, …) or a custom one the tree already uses. Multiple refs: JSON array or one multiline / |-separated string.
create_tagCreate TagA

Create a tag: a colored label such as "To check" or "Line of John Smith" for grouping records. Returns the new handle, Gramps ID and name, with next steps. Does not check for duplicate names: look through list_objects(objectType: "tags") first. The tag labels nothing yet: add its handle to the tagHandles of each record (their create or update tool, linkMode add on update). Tags cannot be renamed here.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesTag name shown on records (required).
colorNoColor as six hex digits RRGGBB without #, e.g. FF5733; stored as given. Default 000000 (black).000000
priorityNoSort priority among tags in Gramps (default 0).

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (which only declare this is a non-read-only, non-destructive write), the description discloses the return payload (new handle, Gramps ID, name), that duplicate names are not checked, that the tag is inert until linked to records, and that renaming is out of scope. This is rich behavioral context an agent cannot get from the structured fields.

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 purpose, then workflow guidance, with no filler sentences. It is dense, and the parenthetical asides ("their create or update tool, linkMode add on update") pack a lot into one clause, but each sentence still carries distinct information.

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 3-parameter creation tool with no output schema, the description covers what it returns, the duplicate-handling gap, and how the created object gets used downstream. Nothing an agent needs to call it correctly and use the result 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 name, color format (six hex digits, no #) and priority are already fully documented in the schema. The description adds no parameter-level syntax or constraints beyond that, 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 tag") and immediately defines what a tag is ("a colored label such as 'To check'... for grouping records"), which distinguishes it from the other create_* siblings. An agent knows exactly what object this produces.

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?

Explicitly names the prerequisite alternative ("Does not check for duplicate names: look through list_objects(objectType: 'tags') first") and gives the follow-up path (add the handle to tagHandles via the record's create/update tool with linkMode add). It also states the exclusion "Tags cannot be renamed here," which prevents misuse.

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

delete_objectDelete ObjectA
Destructive

Permanently delete one record; it cannot be undone through this server. Call it only after the user confirmed this exact record. If other records still point to it, nothing is deleted and the reply lists those backlinks by type; unlink them first with the owners' update tools, or pass force=true after a separate confirmation. On success returns the type, action: deleted and the handle; a missing record returns a not-found message.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNotrue deletes even when other records still point to it, leaving those links dangling (default false).
handleYesThe record to delete. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
objectTypeYesRecord type: person, family, event, place, source, citation, note, media, repository or tag.

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true, but the description goes further: deletion is permanent and not undoable via this server, backlinked records block deletion and are returned grouped by type, force leaves dangling links, and it describes both the success payload (type, action: deleted, handle) and the not-found case.

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?

Four dense sentences, front-loaded with the destructive/permanent nature and the confirmation precondition, then failure mode, then return behavior. No filler or repetition of the tool name.

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?

With no output schema, the description supplies the return contract (type, action: deleted, handle; not-found message), the failure path, and the required user confirmation. An agent has everything needed to invoke it safely.

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 would be 3; however the description adds a genuine parameter-specific rule not present in the schema — force=true requires a separate confirmation and produces dangling links. That meaningfully enriches the force parameter beyond its schema text.

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 ('Permanently delete one record') plus scope ('one record') and irreversibility. It is immediately distinguishable from the many create_*/update_* siblings and from non-destructive readers like get_object.

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?

Explicit preconditions: call only after the user confirmed this exact record; if backlinks exist, unlink them first with the owners' update tools; force=true requires a separate confirmation. This covers when to use it, when it will fail, and the alternative path.

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

get_bookmarksGet BookmarksA
Read-only

List the records bookmarked in this tree, grouped by type (people, families, events, places, sources, citations, repositories, media, notes), each as a one-line summary with its handle. Bookmarks belong to the tree and are shared by all its users; they are set in Gramps Web or Gramps desktop, not through this server, and a tree may have none. Use it to start from the records the tree's users marked; to find records by name use search, to browse one type use list_objects, for recent edits use get_recent_changes.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely non-obvious context beyond that: bookmarks are tree-scoped and shared by all users, they are created outside this server (Gramps Web/desktop) so this tool cannot set them, and a tree may legitimately return none. It does not discuss pagination or ordering, which is a minor remaining gap.

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 purpose and return format, then a second sentence covering ownership/origin caveats and an alternative-routing clause. It is dense but every clause carries information; the type enumeration makes the first sentence long, though that detail is arguably load-bearing.

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?

No output schema exists, yet the description supplies the return contract (grouped by type, one-line summary plus handle) and the empty-result case. Combined with the crisp sibling routing, an agent has everything needed to select and call this tool correctly.

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?

The tool takes zero parameters, so the baseline is 4 by rule. The description correctly implies a parameterless, tree-scoped call and adds no misleading input expectations.

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 (List) and resource (records bookmarked in this tree) and goes further by naming the exact grouping and output shape (one-line summary with its handle). The nine bookmark types are enumerated, so an agent knows precisely what comes back without opening 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?

Explicitly names three alternatives with the condition that selects each: search for records by name, list_objects to browse one type, get_recent_changes for recent edits. It also gives a positive when-to-use ('start from the records the tree's users marked'), which is exactly the routing an agent needs among these siblings.

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

get_objectGet ObjectA
Read-only

Read one record: its fields, its links to other records, and the records that point to it (backlinks, read-only here). Use it once you know the Gramps ID or handle; to find a record by text use search, to browse a type use list_objects. A missing record returns a not-found message with a hint. For a person's relatives or dated events, get_person_tree and get_timeline are shorter.

ParametersJSON Schema
NameRequiredDescriptionDefault
extendedNoPeople and families only: also resolve the linked records (event dates and places, note text, tag names, citations, media) in the same call; default false is faster. Rejected for other types.
identifierYesGramps ID (e.g. I0001) or handle. ID prefixes give the type: I person, F family, E event, P place, S source, C citation, N note, O media, R repository, T tag.
objectTypeNoRecord type: person, family, event, place, source, citation, note, media, repository or tag. Omit for a Gramps ID; required for a handle.

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: backlinks are read-only here, and a missing record returns a not-found message with a hint — useful failure-mode disclosure. It stops short of describing pagination or link volume limits, so not a 5.

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?

Three tight sentences, front-loaded with what the tool returns before the routing rules. No filler or restated naming.

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?

With no output schema, the description still characterizes the return payload (fields, links, backlinks) and the not-found case, and the fully documented schema covers inputs. An agent has everything needed to call this correctly.

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%, including the ID-prefix mapping and the extended flag's type restrictions and performance tradeoff, so the schema does the heavy lifting. The description reinforces that an ID or handle is needed but adds no syntax or format detail beyond the schema. 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 ("Read one record") and enumerates the returned scope: fields, links, and backlinks. It also names the sibling tools it is not (search, list_objects), so an agent can distinguish it without opening a 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?

Gives explicit routing conditions: use once the Gramps ID or handle is known, use search for text lookup, list_objects for browsing a type, and get_person_tree/get_timeline for relatives or dated events. Alternatives and the conditions that select them are all present.

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

get_person_treeGet Person TreeA
Read-only

List a person's ancestors or descendants up to 10 generations deep: one row per relative with the generation, an optional kinship label (Father's mother, Granddaughter), name, Gramps ID, birth and death with places, and handle. Ancestors follow the person's parent families; descendants follow the children of families where the person is a parent, so relatives not linked that way are missing. For how two given people are related use get_relations; for dated events around one person use get_timeline; for one full record use get_object.

ParametersJSON Schema
NameRequiredDescriptionDefault
personYesThe person to start from. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
directionYesancestors (parents, grandparents, …) or descendants (children, grandchildren, …).
generationsNoHow many generations to walk, 1–10 (default 3); other values are clamped.
kinshipLabelsNoWhen true (default), add kinship text such as Father's mother or Granddaughter. When false, show only generation numbers.

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already establish the read-only, non-destructive profile, and the description adds real substance: the row-by-row return shape, the traversal semantics (ancestors via parent families, descendants via children of families where the person is a parent), and the caveat that relatives not linked that way are omitted. It does not cover performance or pagination behavior, which keeps it short of a 5.

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 return shape and traversal semantics are front-loaded, and the routing sentence at the end is dense but purposeful. Slightly long, but every clause carries information an agent needs.

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, so the description's enumeration of returned fields (generation, kinship label, name, Gramps ID, birth/death with places, handle) substitutes for it well. Combined with the coverage caveat and sibling routing, nothing essential is missing for correct invocation.

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 coverage is 100%, so all four parameters are already documented with defaults and clamping behavior. The description only echoes the 10-generation cap and kinship-label concept, so it adds little beyond the schema; baseline 3 is appropriate.

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 (List) plus resource (a person's ancestors or descendants) and scope (up to 10 generations). It explicitly distinguishes itself from get_relations, get_timeline, and get_object, so an agent can route between siblings without opening schemas.

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?

Names three alternatives with the condition that selects each: get_relations for how two people are related, get_timeline for dated events around one person, get_object for one full record. It also flags a when-not case implicitly by stating which relatives are missing from the traversal.

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

get_recent_changesGet Recent ChangesA
Read-only

Show the tree's recent edit history, newest first: commit time (UTC), description, user, an undo marker, and each changed object's class, change kind (added/updated/deleted) and handle, up to 10 objects per transaction. A link added or removed between objects appears as Reference from one handle to the other. Use it to see what was changed last and by whom, or to check that your own writes landed; for the dated events of one person use get_timeline, and read a changed record with get_object.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoHow many transactions to show, 1–100 (default 20); other values are clamped.

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: newest-first ordering, UTC timestamps, an undo marker, and a 10-object-per-transaction truncation cap. It stops short of explaining how to retrieve beyond that cap or any pagination semantics.

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 purpose before diving into return contents and alternatives. Dense but every clause (field list, undo marker, Reference representation, alternatives) carries information; only the per-transaction object cap could be trimmed or clarified.

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?

With no output schema, the description carries the full burden of describing return values and does so thoroughly (field list, ordering, unit of time, link representation). The lone parameter is covered by the schema, and alternatives are named, so an agent has everything needed to call it correctly.

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% and the single limit parameter is fully documented in the schema (range 1–100, default 20, clamping behavior). The description adds nothing for it, which is the correct baseline when the schema does the heavy lifting, but no extra meaning is contributed.

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 ("Show the tree's recent edit history") and enumerates the exact fields returned, including ordering, UTC commit time, undo marker, per-object class/change kind/handle, and the Reference representation for links. It clearly distinguishes itself from get_timeline and get_object by name.

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?

Gives two explicit use cases ("see what was changed last and by whom" and "check that your own writes landed") and routes the agent to alternatives with the selecting condition: get_timeline for dated events of one person, get_object to read a changed record.

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

get_referenceGet ReferenceA
Read-only

Read the server's reference text before writing when a format or type is unclear. Topics: input-guide (how to write dates, names, link updates and structured fields such as attributes and addresses), types (the valid event, role, place, note and other types, including custom ones the tree uses), metadata (server and tree info), and name-settings (name display formats and surname groups). section narrows the reply to one part; an unknown topic or section is rejected with the valid ones. The same texts are MCP resources (gramps://input-guide and so on) for clients that read resources.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesWhich reference: input-guide, types, metadata or name-settings.
sectionNoOne part only (optional; omit for the whole topic). input-guide: dates, name_schema, link_updates, structured_fields, or one of structured_fields.names, .attributes, .urls, .addresses, .person_associations, .repository_refs. types: a category such as event_types or place_types. name-settings: formats or groups. metadata has no sections.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior: section narrows the reply to one part, and an unknown topic/section is rejected with the valid ones listed. It also discloses that the same texts exist as resources.

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 primary instruction ('Read ... before writing'), followed by topic enumeration and the section caveat. It is dense and information-rich, though the topic list is slightly long relative to the action; every sentence still carries meaning.

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?

There is no output schema, but the description compensates by describing what each topic's text contains (date/name/link formats, valid type categories, server/tree info, name display settings). Return format isn't specified, but an agent has enough to call it correctly.

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 the schema already documents topic and section in detail, including valid section values per topic. The description restates the topic list and the section-narrowing behavior without adding format or syntax beyond the schema, 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+resource (read the server's reference text) and enumerates exactly what it covers: input-guide, types, metadata, name-settings. This clearly distinguishes it from the write-focused siblings (create_*, update_*) and from get_object/get_timeline.

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 trigger ('before writing when a format or type is unclear') and names an alternative access path (the same content is available as MCP resources). It stops short of saying when not to use it, but the intended context is unambiguous.

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

get_relationsGet RelationsA
Read-only

Explain how two people are related, read as 'person 2 is the X of person 1' (e.g. 'third cousin twice removed', 'husband'): the closest relationship with generations to the common ancestor, then every relationship found with its common ancestors by name. Searches blood relatives up to 15 generations plus spouses; unrelated people get a clear message. Find both people first with search. To list a whole line of ancestors or descendants use get_person_tree.

ParametersJSON Schema
NameRequiredDescriptionDefault
handle1YesPerson 1, the one the relationship is told from. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
handle2YesPerson 2, the one whose relationship to person 1 is named. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real behavioral scope: blood relatives up to 15 generations plus spouses, and an explicit edge-case behavior for unrelated people (a clear message rather than silence). It does not cover performance or pagination, which keeps it short of a 5.

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 semantics and direction convention, then the return shape, then scope limits and the sibling routing. Every sentence carries information, though the single dense paragraph packs several distinct ideas without visual separation.

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?

No output schema exists, and the description compensates by describing the result content: the closest relationship with generations to the common ancestor, followed by every relationship found with its common ancestors by name. Combined with the scope limits and prerequisite, an agent has everything needed to call it correctly.

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% and both parameters already document handle/Gramps ID resolution, so the baseline is 3. The description goes beyond that by defining the semantic asymmetry of the two handles — the relationship is told from person 1 and named for person 2 — which the schema alone does not convey as clearly.

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 (explain how two people are related) and immediately pins down the reading convention: 'person 2 is the X of person 1', with concrete examples. It also names what it is not, steering the agent away from get_person_tree for line-of-descent queries.

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?

Gives explicit prerequisites ('Find both people first with search') and names the alternative tool with the condition that selects it ('To list a whole line of ancestors or descendants use get_person_tree'). Nothing about when to pick this tool is left to inference.

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

get_timelineGet TimelineA
Read-only

List the dated events around one person, family or place in date order: date, event type, place, and whose event it is, with Gramps IDs. Use it to check a life's sequence or gaps; for the full record use get_object, for ancestors or descendants use get_person_tree, for how two people are related use get_relations. Filter by event category and dates. Without dates, a person timeline lists relatives' events from their whole lives, also before the person's birth and after their death; pass dates to narrow it. Place timelines are computed from direct event backlinks; child places are not included.

ParametersJSON Schema
NameRequiredDescriptionDefault
datesNoOnly events in these dates, written like any date: a year (1850), month (1850-03), day, or range (1850-1860, between 1850-03 and 1851). from and to include the date, before and after leave it out: from 1850, before 1900-05-01. Other calendars are converted: 1856-07-20 (Julian). The Gramps Web form 1850/1/1-1860/12/31 also works. Approximate dates (about, estimated) are rejected.
eventsNoOnly these event categories (omit for all): vital, family, religious, vocational, academic, travel, legal, residence, other, custom.
relativesNoPerson timelines only: whose events to add: father, mother, brother, sister, wife, husband, son, daughter.
identifierYesThe person, family or place. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
objectTypeYesWhose timeline: person, family or place.
relativeEventsNoPerson timelines only: event categories to show for those relatives, same values as events.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only cover the safety profile (readOnlyHint), so the description must carry behavioral burden and it does: it discloses that an undated person timeline pulls relatives' events across their whole lives including before the person's birth and after death, and that place timelines are computed from direct event backlinks with child places excluded. These are non-obvious semantics an agent could not infer from annotations or schema.

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?

Dense but front-loaded: purpose and returned fields come first, then sibling routing, then filtering and edge-case semantics. Every sentence carries information, though the description runs long and could be trimmed slightly without loss.

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?

No output schema exists, but the description compensates by naming the returned fields and covering the tricky cases (undated person timelines, place-backlink computation, date filtering behavior). Nothing essential for correct invocation 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 the schema already documents all six parameters in detail (date syntax, category enums, relative roles). The description adds only a high-level 'Filter by event category and dates' plus the dates-narrowing hint, which is largely redundant with the schema. 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 ('List the dated events around one person, family or place in date order') and enumerates the returned fields (date, event type, place, whose event, Gramps IDs). It also names the sibling tools it is not (get_object, get_person_tree, get_relations), so an agent can disambiguate without opening any 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?

Explicitly routes: 'for the full record use get_object, for ancestors or descendants use get_person_tree, for how two people are related use get_relations', plus the positive use case ('check a life's sequence or gaps'). Both when-to-use and when-to-use-something-else are stated.

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

list_objectsList ObjectsA
Read-only

List the records of one type, a page at a time, optionally filtered and sorted: one line per record (Gramps ID, summary, handle) with the page and total count. Use it to browse a type, look up one Gramps ID, list the citations of a source, or filter by fields with Gramps Query Language; to find records by text use search, and to read one record in full use get_object.

ParametersJSON Schema
NameRequiredDescriptionDefault
gqlNoFilter in Gramps Query Language, run on the server, e.g. gender == 1 or media_list.length >= 1 (optional).
pageNoPage number, from 1 (default 1).
sortNoField to sort by, e.g. gramps_id; a leading - sorts descending, e.g. -change for latest edits first (optional).
grampsIdNoOnly the record with this Gramps ID, e.g. I0001 (not a handle; optional).
pagesizeNoRecords per page, 1–100 (default 20).
objectTypeYesWhich records to list: people, families, events, places, sources, citations, repositories, notes, media or tags.
sourceHandleNoWith objectType citations only: list just the citations of this source; combined with gql by and (optional). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: results are one line per record (Gramps ID, summary, handle) with page and total count, and it discloses pagination semantics. It does not discuss error behavior or server-side GQL limits, so not a 5.

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?

A single dense paragraph that front-loads the core action and output shape before the usage routing. Every clause carries information, though the sentence is long and slightly run-on; it is compact rather than bloated.

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?

Given seven parameters, no output schema, and a large sibling set, the description covers purpose, output format, pagination, usage scenarios, and alternative routing. Nothing an agent needs to call 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 the schema already documents all seven parameters with examples (GQL syntax, sort direction, pagesize range, sourceHandle usage). The description alludes to filtering/sorting/pagination and singles out the citation-listing use case but adds no format detail beyond the schema, so baseline 3 is appropriate.

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 (List) and resource (records of one type) plus scope (paginated, filtered, sorted). It names the siblings it is not (search for text retrieval, get_object for full-record reads), so an agent can distinguish it without opening either 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?

Enumerates concrete use cases: browse a type, look up one Gramps ID, list citations of a source, filter with GQL. Explicitly routes to alternatives with conditions ('to find records by text use search', 'to read one record in full use get_object').

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

read_mediaRead MediaA
Read-only

Download a media file's bytes so you can see it. Default mode thumbnail renders a JPEG preview (PNG when transparent) from an image original as MCP image content, 1568 pixels on the long edge unless size is given; EXIF and other metadata are stripped. Prefer it for reading photos and document scans. Use mode file only when the original is needed: returns image, audio, or embedded blob resource content according to MIME type. Requires GRAMPS_MEDIA_RESOURCES_ENABLED=true and respects size and private-record safeguards. For the media record itself (path, description, links) use get_object; to change it use update_media.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoDownload mode: thumbnail | file. Default thumbnail. Use file only when a preview is insufficient.thumbnail
sizeNoThumbnail long edge in pixels, 1 to 4096; default 1568, which keeps handwriting and small print legible. Use 512 or less for a quick look at photos. Images are never upscaled. Only valid for mode thumbnail; omit for mode file.
handleYesThe media object to show. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint/destructiveHint, but the description adds substantial context: thumbnail renders JPEG (PNG when transparent) at 1568px, EXIF/metadata are stripped, the original is served per MIME type, and it requires GRAMPS_MEDIA_RESOURCES_ENABLED=true with size and private-record safeguards. This greatly exceeds what the annotations convey.

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 purpose, then mode behavior, then prerequisites and sibling routing. The paragraph is dense and cohesive, but a few clauses (rendering-fallback detail) push length; each still earns its place, so only slightly less than ideal.

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?

With no output schema, the description carries the return-value burden and does so: it specifies MCP image content, the JPEG/PNG choice, the blob resource content for audio/original modes, and the required environment flag. An agent has everything needed to invoke it correctly.

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 baseline is 3; the description nonetheless adds meaning beyond the schema by noting images are never upscaled and that the default resolves handwriting and small print. It reinforces mode semantics, though it doesn't add much beyond the already-detailed schema for 'size' and 'handle'.

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: 'Download a media file's bytes so you can see it,' then immediately clarifies the two operational modes (thumbnail vs file). It explicitly distinguishes itself from siblings by naming get_object (for the record) and update_media (for edits), so an agent can route correctly without opening schemas.

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?

Gives explicit when-to-use ('Prefer it for reading photos and document scans'), when-not ('Use mode file only when the original is needed'), and alternatives ('For the media record itself... use get_object; to change it use update_media'). Nothing is left to inference.

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

update_citationUpdate Citation

Change an existing citation: its source, page, confidence, date, notes, media, tags, attributes or the private flag. 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. Returns the handle and Gramps ID; a missing citation returns a not-found message. Which people and events it supports is stored on them (their citationHandles), not here. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoNew date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected.
pageNoNew page, act or entry number. Omit to leave unchanged. Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text.
handleYesThe citation to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
attributesNoAttributes. 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. Each attribute takes only type, value and private.
confidenceNoNew confidence: Very Low, Low, Normal, High or Very High. Omit to leave unchanged.
tagHandlesNoTags. 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":"…"}.
noteHandlesNoNotes. 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":"…"}.
mediaHandlesNoMedia. 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":"…"}.
sourceHandleNoAnother source to cite instead. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
update_eventUpdate Event

Change an existing event: type, date, place, description, citations, notes, media, tags, attributes or the private flag. 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. Returns the handle and Gramps ID; a missing event returns a not-found message, and an unknown type or unreadable date is rejected before anything is saved. Who takes part is stored on the people and families (their eventRefs), not on the event. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoNew date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected.
handleYesThe event to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
eventTypeNoNew event type. 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").
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
attributesNoAttributes. 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.
tagHandlesNoTags. 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":"…"}.
descriptionNoNew description. Omit to leave unchanged.
noteHandlesNoNotes. 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":"…"}.
placeHandleNoNew place. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
mediaHandlesNoMedia. 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":"…"}.
citationHandlesNoCitations. 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":"…"}.
update_familyUpdate Family

Change an existing family: father, mother, relationship type, children, family events, citations, notes, media, tags, attributes or the private flag. 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. Returns the handle and Gramps ID; a missing family returns a not-found message. To add one child, pass it in childRefs with linkMode add. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
handleYesThe family to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
childRefsNoChildren 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.).
eventRefsNoFamily 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).
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
attributesNoAttributes. 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.
sortEventsNotrue 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).
tagHandlesNoTags. 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":"…"}.
noteHandlesNoNotes. 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":"…"}.
fatherHandleNoNew father. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
mediaHandlesNoMedia. 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":"…"}.
motherHandleNoNew mother. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
citationHandlesNoCitations. 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":"…"}.
relationshipTypeNoRelationship 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").
update_mediaUpdate Media

Change an existing media record: description, date, attributes, notes, tags, citations or the private flag. The file itself cannot be uploaded or replaced here; media objects are created in Gramps Web. 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. Returns the handle and Gramps ID; a missing media object returns a not-found message, and an unreadable date is rejected before anything is saved. To show the media on a person, event or citation, add it to their mediaHandles (linkMode add). Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoNew date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected.
handleYesThe media object to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
attributesNoAttributes. 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.
tagHandlesNoTags. 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":"…"}.
descriptionNoNew description (caption). Omit to leave unchanged.
noteHandlesNoNotes. 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":"…"}.
citationHandlesNoCitations. 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":"…"}.
update_noteUpdate NoteA

Change an existing note: its text, type, format, tags or private flag; new text replaces the whole body. 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. Returns the handle and Gramps ID; a missing note returns a not-found message. Which records the note is attached to is stored on them (their noteHandles), not here.

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoNew text, replacing the whole body; changed text loses the styling and links of the old one, the same text keeps them. Omit to leave unchanged.
formatNoPlain or Html. Omit to leave unchanged.
handleYesThe note to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
noteTypeNoNew note type. 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").
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
tagHandlesNoTags. 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":"…"}.

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses significant non-obvious behavior: changed text loses styling/links, replace mode with [] empties the list entirely, the not-found response, and what is returned (handle and Gramps ID). It also clarifies that attachment membership lives on the referencing records, not the note.

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 core mutation is front-loaded and the title of the operation is unambiguous. It is dense and semicolon-heavy across one long block, but nearly every clause carries actionable information rather than filler.

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 7-parameter mutation tool with no output schema, the description covers return values, error behavior (missing note), the replace/add/remove semantics of link lists, and the empty-list edge case. An agent has enough to invoke it correctly without further inference.

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 the schema already documents every parameter in depth; baseline is 3. The description restates and synthesizes much of that (linkMode, empty-list removal) and adds the noteHandles scope clarification, but adds little syntax or semantics not already in the structured fields.

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 ('Change an existing note') and enumerates exactly what is mutable: text, type, format, tags, private flag. This clearly separates it from siblings like create_note, delete_object, and the various update_* tools for other record types.

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?

It gives strong invocation guidance — 'Pass only what changes; omitted arguments stay as they are' and the linkMode rules, plus advice to use separate calls to add and remove. It doesn't explicitly name an alternative tool for specific scenarios, but the when-to-use context is clear.

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

update_personUpdate Person

Change an existing person: names, gender, links to events, families, citations, notes, media and tags, attributes, addresses, URLs, associations or the private flag. 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. Returns the handle and Gramps ID; a missing person returns a not-found message. Links live on one side: to link an event to this person, update the person (linkMode add), not the event. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
urlsNoURLs. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. URLs: JSON array of {type,path,desc}, or strings "Web Home: https://…" with optional " — note" after URL, or lines/| separated. A type must be a standard Gramps URL type (E-mail, Web Home, Web Search, FTP, Unknown) or a custom one the tree already uses. Grammar: gramps://input-guide.
genderNoGender: Female, Male, or Unknown. Omit to leave unchanged.
handleYesThe person to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
addressesNoAddresses. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Addresses: JSON array of Gramps address objects; or text blocks with lines like street:, city:, … (blank line or --- between addresses); or one plain line = street only. Grammar: gramps://input-guide.
eventRefsNoEvents this person takes part in, with roles. In replace mode the list must hold every event the person keeps. 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).
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
attributesNoAttributes. 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.
sortEventsNotrue 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).
tagHandlesNoTags. 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":"…"}.
noteHandlesNoNotes. 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":"…"}.
primaryNameNoNew primary name; replaces the whole current one. Omit to leave unchanged. Name: full Gramps name JSON (see gramps://input-guide), a plain string ("Married Name:: Jane|Smith"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Name types and origins must be standard Gramps ones or custom ones the tree already uses. Plain full-name strings (name/text/full or "Given Middle Surname") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field.
mediaHandlesNoMedia. 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":"…"}.
familyHandlesNoFamilies where this person is a parent or spouse. 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":"…"}.
alternateNamesNoAlternate names. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Alternate names: array of strings ("Married Name:: Jane|Smith"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). Name types and origins must be standard Gramps ones or custom ones the tree already uses. For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |).
citationHandlesNoCitations. 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":"…"}.
personAssociationsNoAssociations with other people (godfather, friend, …). Omit to keep; applied per linkMode. Person associations (handles, not Gramps IDs): JSON array of {ref, rel, ...}, or strings "PERSON_HANDLE:: Godfather" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide.
parentFamilyHandlesNoFamilies where this person is a child. 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":"…"}.
update_placeUpdate Place

Change an existing place: name with its language and date, type, coordinates, enclosing places, alternate names, code, and links to notes, media, citations and tags. 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. Returns the handle and Gramps ID with the stored name, type, coordinates and enclosing places; a missing place returns a not-found message. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
latNoLatitude in decimal degrees, north positive (52.2297). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. Omit to keep the current value; pass an empty string to remove it.
lonNoLongitude in decimal degrees, east positive (21.0122). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. Omit to keep the current value; pass an empty string to remove it.
codeNoNew place code. Omit to leave unchanged.
nameNoNew primary name. Omit to leave unchanged.
handleYesThe place to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
linkModeNoHow 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
nameDateNoWhen the primary name applies. Omit to keep the current date; pass an empty string to remove it. Gramps shows the first name, primary first, whose date is empty or matches the event date, so an undated primary name hides dated alternate names: date the primary name too ("from 1937-02-10"). Dashes are spans; open "1991-" / "from 1991" are From. Unreadable dates are rejected.
nameLangNoLanguage code of the primary name. Omit to leave unchanged.
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
placeTypeNoNew place type. 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").
enclosedByNoPlaces that contain this one. Omit to keep; applied per linkMode. Parent place refs via enclosedBy (not enclosedByHandles): handle or Gramps ID, array of them, JSON array of {ref, date?}, or shorthand "HANDLE::1920-1950" (date optional). Place dashes are spans (from…to); open "1991-" / "from 1991" are From. English months OK: "HANDLE::from 1 Oct 1929 to 27 Sep 1937". Examples: [{ref:"…", date:"1708-1927"}], "HANDLE::1991-", date "1703-1914-08-31". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: "input-guide", section: "dates").
tagHandlesNoTags. 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":"…"}.
noteHandlesNoNotes. 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":"…"}.
mediaHandlesNoMedia. 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":"…"}.
alternateNamesNoAlternate names. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Alternate place names: array of strings ("Old Name" or "Old Name::de"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:"New York", date:"1914-08-31-1924-01-26"}] or date "from 5 Jul 1944". Place dashes are spans (from…to); open "1991-" / "from 1991" are From. Unrecognized dates fail validation (see get_reference(topic: "input-guide", section: "dates")).
citationHandlesNoCitations. 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":"…"}.
update_repositoryUpdate RepositoryA

Change an existing repository: name, type, address, website, notes, tags or the private flag. 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. Returns the handle and Gramps ID; a missing repository returns a not-found message, and an unknown type is rejected before anything is saved. Which sources it holds is stored on the sources (their repositoryHandles), not here.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlNoNew website; replaces every stored link, and an empty string removes them. Omit to leave unchanged.
nameNoNew name. Omit to leave unchanged.
handleYesThe repository to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
addressNoNew postal address as one line; replaces every stored address, and an empty string removes them. Omit to leave unchanged.
linkModeNoHow 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
repoTypeNoNew type, e.g. Archive, Library, Church. 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").
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
tagHandlesNoTags. 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":"…"}.
noteHandlesNoNotes. 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":"…"}.

TDQS

A4.6/5.0
Behavior5/5

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description carries real weight: it discloses that replace mode with [] REMOVES every link of that kind, that unknown types are rejected before saving, that a missing handle yields a not-found message, and what is returned (handle and Gramps ID). This is precisely the destructive/error semantics an agent needs and annotations do not supply.

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 mutable fields and the omit-means-unchanged rule are front-loaded, followed by linkMode semantics, return/error behavior, and one scoping caveat. Dense but every sentence carries information; the linkMode sentence is long and partially overlaps the schema, which keeps it from a 5.

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 9-parameter mutation tool with no output schema, the description covers the update contract, the linkMode matrix, the return value, and the two failure modes (missing handle, unknown type). Nothing needed 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.

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 earns extra by explaining how linkMode interacts across all supplied link lists and by clarifying a conceptual boundary not in the schema (which sources a repository holds lives on the sources' repositoryHandles, not here). Some linkMode wording duplicates the schema, but the cross-parameter framing adds meaning.

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 (Change) and resource (an existing repository), then enumerates the mutable fields, so the agent immediately knows this is a partial-update for repositories and not for people, sources, or families. It is readily distinguishable from the other update_* siblings by the resource it names.

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?

"Pass only what changes; omitted arguments stay as they are" is a clear usage contract, and "Use separate calls to add and remove" gives concrete operational guidance for linkMode. It stops short of explicitly contrasting with create_repository or delete_object, so the alternative-selection guidance is implied rather than stated.

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

update_sourceUpdate Source

Change an existing source: title, author, publication info, abbreviation, repositories, notes, media, tags, attributes or the private flag. 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. Returns the handle and Gramps ID; a missing source returns a not-found message. Formats of every argument: get_reference(topic: "input-guide").

ParametersJSON Schema
NameRequiredDescriptionDefault
titleNoNew title. Omit to leave unchanged.
abbrevNoNew abbreviation. Omit to leave unchanged.
authorNoNew author. Omit to leave unchanged.
handleYesThe source to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
pubinfoNoNew publication info. Omit to leave unchanged.
linkModeNoHow 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
isPrivateNotrue makes the record private, false public. Omit to leave unchanged.
attributesNoAttributes. 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. Each attribute takes only type, value and private.
tagHandlesNoTags. 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":"…"}.
noteHandlesNoNotes. 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":"…"}.
mediaHandlesNoMedia. 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":"…"}.
repositoryHandlesNoRepositories that hold the source. Omit to keep; applied per linkMode. Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings "Ref : CallNumber : MediaType". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: "Ref : CallNumber" and "Ref :: MediaType" are valid. MediaType must be a standard Gramps source media type (Book, Manuscript, Film, Photo, …) or a custom one the tree already uses. Multiple refs: JSON array or one multiline / |-separated string.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 11 tool updatesv2.3.2
    • Changedcreate_citation1 field changed
      • changedInput schema / properties / attributes / description
        Previous value: -"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. Each attribute takes only type, value and private."New value: +"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. Each attribute takes only type, value and private."
    • Changedcreate_event1 field changed
      • changedInput schema / properties / attributes / description
        Previous value: -"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: 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."
    • Changedcreate_family3 fields changed
      • changedInput schema / properties / attributes / description
        Previous value: -"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: 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, each with its relation to the father and mother (Birth by default; Adopted, Stepchild, …). 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, each with its relation to the father and mother (Birth by default; Adopted, Stepchild, …). 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: -"Existing family events such as Marriage or Divorce. 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: +"Existing family events such as Marriage or Divorce. 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)."
    • Changedcreate_person5 fields changed
      • changedInput schema / properties / alternateNames / description
        Previous value: -"Alternate names: array of strings (\"Married Name:: Jane|Smith\"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |)."New value: +"Alternate names: array of strings (\"Married Name:: Jane|Smith\"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). Name types and origins must be standard Gramps ones or custom ones the tree already uses. For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |)."
      • changedInput schema / properties / attributes / description
        Previous value: -"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: 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 / eventRefs / description
        Previous value: -"Existing events this person takes part in, each with a role (Primary by default; Witness, Godparent, …). 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: +"Existing events this person takes part in, each with a role (Primary by default; Witness, Godparent, …). 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)."
      • changedInput schema / properties / primaryName / description
        Previous value: -"Name: full Gramps name JSON (see gramps://input-guide), a plain string (\"Married Name:: Jane|Smith\"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Plain full-name strings (name/text/full or \"Given Middle Surname\") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field."New value: +"Name: full Gramps name JSON (see gramps://input-guide), a plain string (\"Married Name:: Jane|Smith\"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Name types and origins must be standard Gramps ones or custom ones the tree already uses. Plain full-name strings (name/text/full or \"Given Middle Surname\") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field."
      • changedInput schema / properties / urls / description
        Previous value: -"URLs: JSON array of {type,path,desc}, or strings \"Web Home: https://…\" with optional \" — note\" after URL, or lines/| separated. Grammar: gramps://input-guide."New value: +"URLs: JSON array of {type,path,desc}, or strings \"Web Home: https://…\" with optional \" — note\" after URL, or lines/| separated. A type must be a standard Gramps URL type (E-mail, Web Home, Web Search, FTP, Unknown) or a custom one the tree already uses. Grammar: gramps://input-guide."
    • Changedcreate_source2 fields changed
      • changedInput schema / properties / attributes / description
        Previous value: -"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. Each attribute takes only type, value and private."New value: +"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. Each attribute takes only type, value and private."
      • changedInput schema / properties / repositoryHandles / description
        Previous value: -"Repositories that hold the source, each with an optional call number and media type; the repositories must exist (create_repository). Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. Multiple refs: JSON array or one multiline / |-separated string."New value: +"Repositories that hold the source, each with an optional call number and media type; the repositories must exist (create_repository). Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. MediaType must be a standard Gramps source media type (Book, Manuscript, Film, Photo, …) or a custom one the tree already uses. Multiple refs: JSON array or one multiline / |-separated string."
    • Changedupdate_citation1 field changed
      • 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. Each attribute takes only type, value and private."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. Each attribute takes only type, value and private."
    • Changedupdate_event1 field changed
      • 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."
    • Changedupdate_family4 fields changed
      • 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"
        +}
    • Changedupdate_media1 field changed
      • 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."
    • Changedupdate_person6 fields changed
      • changedInput schema / properties / alternateNames / description
        Previous value: -"Alternate names. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Alternate names: array of strings (\"Married Name:: Jane|Smith\"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |)."New value: +"Alternate names. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Alternate names: array of strings (\"Married Name:: Jane|Smith\"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). Name types and origins must be standard Gramps ones or custom ones the tree already uses. For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |)."
      • 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 / eventRefs / description
        Previous value: -"Events this person takes part in, with roles. In replace mode the list must hold every event the person keeps. 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: +"Events this person takes part in, with roles. In replace mode the list must hold every event the person keeps. 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)."
      • changedInput schema / properties / primaryName / description
        Previous value: -"New primary name; replaces the whole current one. Omit to leave unchanged. Name: full Gramps name JSON (see gramps://input-guide), a plain string (\"Married Name:: Jane|Smith\"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Plain full-name strings (name/text/full or \"Given Middle Surname\") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field."New value: +"New primary name; replaces the whole current one. Omit to leave unchanged. Name: full Gramps name JSON (see gramps://input-guide), a plain string (\"Married Name:: Jane|Smith\"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Name types and origins must be standard Gramps ones or custom ones the tree already uses. Plain full-name strings (name/text/full or \"Given Middle Surname\") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field."
      • 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"
        +}
      • changedInput schema / properties / urls / description
        Previous value: -"URLs. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. URLs: JSON array of {type,path,desc}, or strings \"Web Home: https://…\" with optional \" — note\" after URL, or lines/| separated. Grammar: gramps://input-guide."New value: +"URLs. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. URLs: JSON array of {type,path,desc}, or strings \"Web Home: https://…\" with optional \" — note\" after URL, or lines/| separated. A type must be a standard Gramps URL type (E-mail, Web Home, Web Search, FTP, Unknown) or a custom one the tree already uses. Grammar: gramps://input-guide."
    • Changedupdate_source2 fields changed
      • 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. Each attribute takes only type, value and private."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. Each attribute takes only type, value and private."
      • changedInput schema / properties / repositoryHandles / description
        Previous value: -"Repositories that hold the source. Omit to keep; applied per linkMode. Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. Multiple refs: JSON array or one multiline / |-separated string."New value: +"Repositories that hold the source. Omit to keep; applied per linkMode. Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. MediaType must be a standard Gramps source media type (Book, Manuscript, Film, Photo, …) or a custom one the tree already uses. Multiple refs: JSON array or one multiline / |-separated string."
  2. 1 tool update
    • Addedread_media
  3. 11 tool updatesv2.3.1
    • Changedcreate_citation3 fields changed
      • changedInput schema / properties / attributes / description
        Previous value: -"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: 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. Each attribute takes only type, value and private."
      • changedInput schema / properties / noteHandles / description
        Previous value: -"Notes, e.g. a transcription. 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: +"Notes, e.g. a transcript of the entry (create_note with type Transcript). Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
      • removedInput schema / properties / text
        Removed value: -{
        -  "default": null,
        -  "description": "Citation text or transcript (optional).",
        -  "type": [
        -    "string",
        -    "null"
        -  ]
        -}
    • Changedcreate_source1 field changed
      • changedInput schema / properties / attributes / description
        Previous value: -"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: 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. Each attribute takes only type, value and private."
    • Changedupdate_citation3 fields changed
      • 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. Full grammar: gramps://input-guide. Each attribute takes only type, value and private."
      • 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."
      • removedInput schema / properties / text
        Removed value: -{
        -  "default": null,
        -  "description": "New citation text or transcript. Omit to leave unchanged.",
        -  "type": [
        -    "string",
        -    "null"
        -  ]
        -}
    • Changedupdate_event1 field changed
      • 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."
    • Changedupdate_family1 field changed
      • 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."
    • Changedupdate_media1 field changed
      • 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."
    • Changedupdate_note2 fields changed
      • 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."
      • changedInput schema / properties / text / description
        Previous value: -"New text, replacing the whole body. Omit to leave unchanged."New value: +"New text, replacing the whole body; changed text loses the styling and links of the old one, the same text keeps them. Omit to leave unchanged."
    • Changedupdate_person1 field changed
      • 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."
    • Changedupdate_place1 field changed
      • 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."
    • Changedupdate_repository1 field changed
      • 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."
    • Changedupdate_source2 fields changed
      • 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. Full grammar: gramps://input-guide. Each attribute takes only type, value and private."
      • 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."
  4. 29 tool updatesv2.3.0
    • Removedadd_event_to_person
    • Changedcreate_citation9 fields changed
      • changedInput schema / properties / confidence / description
        Previous value: -"Confidence: Very Low, Low, Normal, High, or Very High (default: Normal)"New value: +"How reliable the cited record is: Very Low, Low, Normal (default), High or Very High."
      • changedInput schema / properties / date / description
        Previous value: -"Access or reference date text. Date format: use ISO dates (1990-03-15), year-only (1920), or modifiers (before 1920, about 1950). Add the calendar at the end for Old Style and other calendars: 1856-07-20 (Julian). See gramps://input-guide resource or call get_reference(topic: \"input-guide\", section: \"dates\") for full syntax."New value: +"Date of the cited entry, optional. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected."
      • changedInput schema / properties / isPrivate / description
        Previous value: -"Mark record private (default: false)"New value: +"Mark the citation private (default false)."
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Media handles (optional). 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 such as the scan of the page. 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 / noteHandles / description
        Previous value: -"Note handles (optional). 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, e.g. a transcription. 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 / page / description
        Previous value: -"Page reference within source (optional). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text."New value: +"Where in the source: page, act or entry number (optional). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text."
      • changedInput schema / properties / sourceHandle / description
        Previous value: -"Source handle (required). 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 source being cited (required). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Tag handles (optional). 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. 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 / text / description
        Previous value: -"Citation text / transcript (optional)"New value: +"Citation text or transcript (optional)."
    • Changedcreate_event9 fields changed
      • changedInput schema / properties / citationHandles / description
        Previous value: -"Citation handles (optional). 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 supporting the event. 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 / date / description
        Previous value: -"Optional event date text. Date format: use ISO dates (1990-03-15), year-only (1920), or modifiers (before 1920, about 1950). Add the calendar at the end for Old Style and other calendars: 1856-07-20 (Julian). See gramps://input-guide resource or call get_reference(topic: \"input-guide\", section: \"dates\") for full syntax."New value: +"When it happened, optional. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected."
      • changedInput schema / properties / description / description
        Previous value: -"Event description (optional)"New value: +"Short description, optional."
      • changedInput schema / properties / eventType / description
        Previous value: -"Event type key from the tree. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values."New value: +"Event type, e.g. Birth, Baptism, Death, Burial, Marriage, Residence, Occupation. 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 / isPrivate / description
        Previous value: -"Mark record private (default: false)"New value: +"Mark the event private (default false)."
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Media handles (optional). 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. 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 / noteHandles / description
        Previous value: -"Note handles (optional). 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. 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 / placeHandle / description
        Previous value: -"Place handle for this event. Optional. 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: +"Where it happened, optional; the place must exist (create_place). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Tag handles (optional). 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. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
    • Changedcreate_family10 fields changed
      • changedInput schema / properties / childRefs / description
        Previous value: -"Child links for this family. 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, each with its relation to the father and mother (Birth by default; Adopted, Stepchild, …). 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: -"Citation handles. 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. 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: -"Events to link to this family. 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: +"Existing family events such as Marriage or Divorce. 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. Optional. 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 father, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / isPrivate / description
        Previous value: -"Mark record private (default: false)"New value: +"Mark the family private (default false)."
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Media handles. 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. 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. Optional. 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 mother, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / noteHandles / description
        Previous value: -"Note handles. 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. 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: Married, Unmarried, Civil Union, Unknown (default: Married)"New value: +"Relationship type: Married (default), Unmarried, Civil Union or Unknown. 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: -"Tag handles. 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. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
    • Changedcreate_note5 fields changed
      • changedInput schema / properties / format / description
        Previous value: -"Text format: Plain or Html (default: Plain)"New value: +"Text format: Plain (default) or Html."
      • changedInput schema / properties / isPrivate / description
        Previous value: -"Mark as private (optional)"New value: +"Mark the note private (default false)."
      • changedInput schema / properties / noteType / description
        Previous value: -"Note type key. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values. Default General."New value: +"Note type, default General; e.g. Research, Transcript, Person Note, Event Note, Citation. 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: -"Tag handles (optional). 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. 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 / text / description
        Previous value: -"Note body text (required)."New value: +"The note text (required)."
    • Changedcreate_person9 fields changed
      • changedInput schema / properties / citationHandles / description
        Previous value: -"Citation handles. 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. 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: -"Event links to attach to this person. 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: +"Existing events this person takes part in, each with a role (Primary by default; Witness, Godparent, …). 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 / familyHandles / description
        Previous value: -"Family handles (where this person is parent/spouse). 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: +"Families where this person is a parent or spouse. 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 / isPrivate / description
        Previous value: -"Mark record as private (default: false)"New value: +"Mark the person private (default false)."
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Media object handles. 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. 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 / noteHandles / description
        Previous value: -"Note handles. 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. 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 / parentFamilyHandles / description
        Previous value: -"Parent family handles (where this person is child). 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: +"Families where this person is a child. Does not add the person to the family's children: use childRefs on the family for that. 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 / personAssociations / description
        Previous value: -"Person associations: JSON array of {ref, rel, ...}, or strings \"PERSON_HANDLE:: Godfather\" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide."New value: +"Person associations (handles, not Gramps IDs): JSON array of {ref, rel, ...}, or strings \"PERSON_HANDLE:: Godfather\" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Tag handles. 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. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
    • Changedcreate_place16 fields changed
      • changedInput schema / properties / alternateNames / description
        Previous value: -"Alternate place names. Alternate place names: array of strings (\"Old Name\" or \"Old Name::de\"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:\"New York\", date:\"1914-08-31-1924-01-26\"}] or date \"from 5 Jul 1944\". Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. Unrecognized dates fail validation (see get_reference(topic: \"input-guide\", section: \"dates\"))."New value: +"Other names: historical, other languages. Alternate place names: array of strings (\"Old Name\" or \"Old Name::de\"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:\"New York\", date:\"1914-08-31-1924-01-26\"}] or date \"from 5 Jul 1944\". Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. Unrecognized dates fail validation (see get_reference(topic: \"input-guide\", section: \"dates\"))."
      • changedInput schema / properties / citationHandles / description
        Previous value: -"Citation handles. 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. 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 / code / description
        Previous value: -"Place code / postal reference (optional)"New value: +"Place code or postal code (optional)."
      • changedInput schema / properties / enclosedBy / description
        Previous value: -"Parent place refs (enclosure hierarchy). Parent place refs via enclosedBy (not enclosedByHandles): handle string, array of handles, JSON array of {ref, date?}, or shorthand \"HANDLE::1920-1950\" (date optional). Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. English months OK: \"HANDLE::from 1 Oct 1929 to 27 Sep 1937\". Examples: [{ref:\"…\", date:\"1708-1927\"}], \"HANDLE::1991-\", date \"1703-1914-08-31\". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: \"input-guide\", section: \"dates\")."New value: +"Places that contain this one. Parent place refs via enclosedBy (not enclosedByHandles): handle or Gramps ID, array of them, JSON array of {ref, date?}, or shorthand \"HANDLE::1920-1950\" (date optional). Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. English months OK: \"HANDLE::from 1 Oct 1929 to 27 Sep 1937\". Examples: [{ref:\"…\", date:\"1708-1927\"}], \"HANDLE::1991-\", date \"1703-1914-08-31\". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: \"input-guide\", section: \"dates\")."
      • changedInput schema / properties / isPrivate / description
        Previous value: -"Mark record private (default: false)"New value: +"Mark the place private (default false)."
      • changedInput schema / properties / lat / description
        Previous value: -"Latitude coordinate"New value: +"Latitude in decimal degrees, north positive (52.2297). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text."
      • removedInput schema / properties / lat / type
        Removed value: -[
        -  "string",
        -  "null"
        -]
      • changedInput schema / properties / lon / description
        Previous value: -"Longitude coordinate"New value: +"Longitude in decimal degrees, east positive (21.0122). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text."
      • removedInput schema / properties / lon / type
        Removed value: -[
        -  "string",
        -  "null"
        -]
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Media handles. 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. 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 / name / description
        Previous value: -"Primary display name (required)."New value: +"Primary name (required)."
      • addedInput schema / properties / nameDate
        Added value: +{
        +  "default": null,
        +  "description": "When the primary name applies (default: always). Gramps shows the first name, primary first, whose date is empty or matches the event date, so an undated primary name hides dated alternate names: date the primary name too (\"from 1937-02-10\"). Dashes are spans; open \"1991-\" / \"from 1991\" are From. Unreadable dates are rejected.",
        +  "type": [
        +    "string",
        +    "null"
        +  ]
        +}
      • changedInput schema / properties / nameLang / description
        Previous value: -"Language code for primary name (default: omitted)"New value: +"Language code of the primary name, e.g. pl or de (optional)."
      • changedInput schema / properties / noteHandles / description
        Previous value: -"Note handles. 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. 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 / placeType / description
        Previous value: -"Place type key. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values."New value: +"Place type, e.g. Country, Province, County, City, Town, Village, Hamlet, Parish. 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: -"Tag handles. 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. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
    • Changedcreate_repository7 fields changed
      • changedInput schema / properties / address / description
        Previous value: -"Street address (optional)"New value: +"Postal address as one line, e.g. \"12 High Street, London\", stored as the street of the repository's address (optional)."
      • changedInput schema / properties / isPrivate / description
        Previous value: -"Mark record private (default: false)"New value: +"Mark the repository private (default: false); Gramps Web hides private records from users not allowed to see them."
      • changedInput schema / properties / name / description
        Previous value: -"Name (required)."New value: +"Name, e.g. \"State Archive in Warsaw\" (required)."
      • changedInput schema / properties / noteHandles / description
        Previous value: -"Note handles (optional). 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: +"Existing notes to link (optional); create them first with create_note. 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 / repoType / description
        Previous value: -"Repository type key. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values."New value: +"Repository type, e.g. Archive, Library, Church, Web site (optional; Gramps stores Library when omitted). 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: -"Tag handles (optional). 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: +"Existing tags to link (optional); create them first with create_tag. 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 / url / description
        Previous value: -"Website URL (optional)"New value: +"Website, e.g. https://archive.example.org, stored as the repository's web home link (optional)."
    • Changedcreate_source8 fields changed
      • changedInput schema / properties / abbrev / description
        Previous value: -"Abbreviation (optional)"New value: +"Short title for lists (optional)."
      • changedInput schema / properties / author / description
        Previous value: -"Author name (optional)"New value: +"Author or issuing body (optional)."
      • changedInput schema / properties / isPrivate / description
        Previous value: -"Mark record private (default: false)"New value: +"Mark the source private (default false)."
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Media handles (optional). 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. 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 / noteHandles / description
        Previous value: -"Note handles (optional). 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. 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 / pubinfo / description
        Previous value: -"Publication info (optional)"New value: +"Publication info: publisher, place, year (optional)."
      • changedInput schema / properties / repositoryHandles / description
        Previous value: -"Repository refs. Repository refs: JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. Multiple refs: JSON array or one multiline / |-separated string."New value: +"Repositories that hold the source, each with an optional call number and media type; the repositories must exist (create_repository). Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. Multiple refs: JSON array or one multiline / |-separated string."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Tag handles (optional). 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. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
    • Changedcreate_tag3 fields changed
      • changedInput schema / properties / color / description
        Previous value: -"Color as six hex digits RRGGBB without #. Default 000000 (black)."New value: +"Color as six hex digits RRGGBB without #, e.g. FF5733; stored as given. Default 000000 (black)."
      • changedInput schema / properties / name / description
        Previous value: -"Display name (required)."New value: +"Tag name shown on records (required)."
      • changedInput schema / properties / priority / description
        Previous value: -"Sort priority; lower often sorts first (default 0)."New value: +"Sort priority among tags in Gramps (default 0)."
    • Changeddelete_object3 fields changed
      • changedInput schema / properties / force / description
        Previous value: -"If true, delete despite backlinks. This may leave dangling references. Default false."New value: +"true deletes even when other records still point to it, leaving those links dangling (default false)."
      • changedInput schema / properties / handle / description
        Previous value: -"Object handle or Gramps ID (for example I0001). Handles are opaque API strings; Gramps IDs are resolved automatically."New value: +"The record to delete. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / objectType / description
        Previous value: -"Object type: person | family | event | place | source | citation | note | media | repository | tag."New value: +"Record type: person, family, event, place, source, citation, note, media, repository or tag."
    • Changedget_object3 fields changed
      • changedInput schema / properties / extended / description
        Previous value: -"For person and family only: resolve linked objects inline. Default: false."New value: +"People and families only: also resolve the linked records (event dates and places, note text, tag names, citations, media) in the same call; default false is faster. Rejected for other types."
      • changedInput schema / properties / identifier / description
        Previous value: -"Object handle or Gramps ID (e.g. I0001). Gramps ID prefixes: I person, F family, E event, P place, S source, C citation, N note, O media, R repository, T tag."New value: +"Gramps ID (e.g. I0001) or handle. ID prefixes give the type: I person, F family, E event, P place, S source, C citation, N note, O media, R repository, T tag."
      • changedInput schema / properties / objectType / description
        Previous value: -"Optional for a Gramps ID, whose prefix determines the type. Required for an opaque handle: person | family | event | place | source | citation | note | media | repository | tag."New value: +"Record type: person, family, event, place, source, citation, note, media, repository or tag. Omit for a Gramps ID; required for a handle."
    • Changedget_person_tree3 fields changed
      • changedInput schema / properties / direction / description
        Previous value: -"Tree direction: ancestors | descendants."New value: +"ancestors (parents, grandparents, …) or descendants (children, grandchildren, …)."
      • changedInput schema / properties / generations / description
        Previous value: -"Number of generations to include (default: 3, max: 10)"New value: +"How many generations to walk, 1–10 (default 3); other values are clamped."
      • changedInput schema / properties / person / description
        Previous value: -"Root person handle or Gramps ID. 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 person to start from. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
    • Changedget_recent_changes1 field changed
      • changedInput schema / properties / limit / description
        Previous value: -"How many history rows (clamped 1–100). Default 20."New value: +"How many transactions to show, 1–100 (default 20); other values are clamped."
    • Changedget_reference2 fields changed
      • changedInput schema / properties / section / description
        Previous value: -"Optional section. input-guide: dates | name_schema | link_updates | structured_fields | structured_fields.names | structured_fields.attributes | structured_fields.urls | structured_fields.addresses | structured_fields.person_associations | structured_fields.repository_refs. types: a category key such as event_types. name-settings: formats | groups. Not supported for metadata."New value: +"One part only (optional; omit for the whole topic). input-guide: dates, name_schema, link_updates, structured_fields, or one of structured_fields.names, .attributes, .urls, .addresses, .person_associations, .repository_refs. types: a category such as event_types or place_types. name-settings: formats or groups. metadata has no sections."
      • changedInput schema / properties / topic / description
        Previous value: -"Reference topic: input-guide | types | metadata | name-settings."New value: +"Which reference: input-guide, types, metadata or name-settings."
    • Changedget_relations2 fields changed
      • changedInput schema / properties / handle1 / description
        Previous value: -"First person 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: +"Person 1, the one the relationship is told from. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / handle2 / description
        Previous value: -"Second person 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: +"Person 2, the one whose relationship to person 1 is named. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
    • Changedget_timeline5 fields changed
      • changedInput schema / properties / events / description
        Previous value: -"Event categories: vital, family, religious, vocational, academic, travel, legal, residence, other, custom."New value: +"Only these event categories (omit for all): vital, family, religious, vocational, academic, travel, legal, residence, other, custom."
      • changedInput schema / properties / identifier / description
        Previous value: -"Person, family, or place handle or Gramps ID."New value: +"The person, family or place. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / objectType / description
        Previous value: -"Timeline owner type: person | family | place."New value: +"Whose timeline: person, family or place."
      • changedInput schema / properties / relativeEvents / description
        Previous value: -"For person only: event categories for the listed relatives."New value: +"Person timelines only: event categories to show for those relatives, same values as events."
      • changedInput schema / properties / relatives / description
        Previous value: -"For person only: include events of father, mother, brother, sister, wife, husband, son, or daughter."New value: +"Person timelines only: whose events to add: father, mother, brother, sister, wife, husband, son, daughter."
    • Changedlist_objects7 fields changed
      • changedInput schema / properties / gql / description
        Previous value: -"Optional. Gramps QL expression executed server-side for filtering."New value: +"Filter in Gramps Query Language, run on the server, e.g. gender == 1 or media_list.length >= 1 (optional)."
      • changedInput schema / properties / grampsId / description
        Previous value: -"Optional. Filter by numeric/string Gramps ID (I0001-style), NOT the opaque handle."New value: +"Only the record with this Gramps ID, e.g. I0001 (not a handle; optional)."
      • changedInput schema / properties / objectType / description
        Previous value: -"Object collection: people | families | events | places | sources | citations | repositories | notes | media | tags (exact spelling, case-insensitive)."New value: +"Which records to list: people, families, events, places, sources, citations, repositories, notes, media or tags."
      • changedInput schema / properties / page / description
        Previous value: -"1-based page. Default 1."New value: +"Page number, from 1 (default 1)."
      • changedInput schema / properties / pagesize / description
        Previous value: -"Page size. Default 20, max 100."New value: +"Records per page, 1–100 (default 20)."
      • changedInput schema / properties / sort / description
        Previous value: -"Optional. Sort field; leading - means descending."New value: +"Field to sort by, e.g. gramps_id; a leading - sorts descending, e.g. -change for latest edits first (optional)."
      • changedInput schema / properties / sourceHandle / description
        Previous value: -"Optional. When objectType is citations, limit to citations of this source 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: +"With objectType citations only: list just the citations of this source; combined with gql by and (optional). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
    • Removedquick_add_person
    • Changedsearch3 fields changed
      • changedInput schema / properties / page / description
        Previous value: -"1-based page index. Default 1."New value: +"Page number, from 1 (default 1)."
      • changedInput schema / properties / pagesize / description
        Previous value: -"Page size. Default 20, maximum 100."New value: +"Hits per page, 1–100 (default 20)."
      • changedInput schema / properties / query / description
        Previous value: -"Query string; * is wildcard. Examples: Smith*, John, Dublin*"New value: +"Words to find; * matches any ending. Examples: Smith*, John, Dublin*, a register title."
    • Changedupdate_citation11 fields changed
      • 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 / confidence / description
        Previous value: -"Confidence: Very Low, Low, Normal, High, Very High. Omit to leave unchanged."New value: +"New confidence: Very Low, Low, Normal, High or Very High. Omit to leave unchanged."
      • changedInput schema / properties / date / description
        Previous value: -"Date text. Omit to keep the current date; pass an empty string to remove it. Date format: use ISO dates (1990-03-15), year-only (1920), or modifiers (before 1920, about 1950). Add the calendar at the end for Old Style and other calendars: 1856-07-20 (Julian). See gramps://input-guide resource or call get_reference(topic: \"input-guide\", section: \"dates\") for full syntax."New value: +"New date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected."
      • changedInput schema / properties / handle / description
        Previous value: -"Citation 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 citation 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. 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 / noteHandles / description
        Previous value: -"Linked notes. 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 / page / description
        Previous value: -"Page within source. Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. Omit to leave unchanged."New value: +"New page, act or entry number. Omit to leave unchanged. Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text."
      • changedInput schema / properties / sourceHandle / description
        Previous value: -"Source 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: +"Another source to cite instead. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Linked tags. 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\":\"…\"}."
      • changedInput schema / properties / text / description
        Previous value: -"Transcript or citation text. Omit to leave unchanged."New value: +"New citation text or transcript. Omit to leave unchanged."
    • Changedupdate_event11 fields changed
      • 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 / citationHandles / description
        Previous value: -"Linked citations. 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 / date / description
        Previous value: -"Event date text. Omit to keep the current date; pass an empty string to remove it. Date format: use ISO dates (1990-03-15), year-only (1920), or modifiers (before 1920, about 1950). Add the calendar at the end for Old Style and other calendars: 1856-07-20 (Julian). See gramps://input-guide resource or call get_reference(topic: \"input-guide\", section: \"dates\") for full syntax."New value: +"New date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected."
      • changedInput schema / properties / description / description
        Previous value: -"Description text. Omit to leave unchanged."New value: +"New description. Omit to leave unchanged."
      • changedInput schema / properties / eventType / description
        Previous value: -"Event type. 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: +"New event type. 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 / handle / description
        Previous value: -"Event 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 event 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. 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 / noteHandles / description
        Previous value: -"Linked notes. 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 / placeHandle / description
        Previous value: -"Place 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 place. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Linked tags. 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\":\"…\"}."
    • Changedupdate_family12 fields changed
      • 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\":\"…\"}."
    • Changedupdate_media8 fields changed
      • 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 / citationHandles / description
        Previous value: -"Linked citations. 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 / date / description
        Previous value: -"Date text. Omit to keep the current date; pass an empty string to remove it. Date format: use ISO dates (1990-03-15), year-only (1920), or modifiers (before 1920, about 1950). Add the calendar at the end for Old Style and other calendars: 1856-07-20 (Julian). See gramps://input-guide resource or call get_reference(topic: \"input-guide\", section: \"dates\") for full syntax."New value: +"New date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected."
      • changedInput schema / properties / description / description
        Previous value: -"Description. Omit to leave unchanged."New value: +"New description (caption). Omit to leave unchanged."
      • changedInput schema / properties / handle / description
        Previous value: -"Media 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 media object 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 / noteHandles / description
        Previous value: -"Linked notes. 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 / tagHandles / description
        Previous value: -"Linked tags. 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\":\"…\"}."
    • Changedupdate_note5 fields changed
      • changedInput schema / properties / handle / description
        Previous value: -"Note 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 note 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 / noteType / description
        Previous value: -"Note type. 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: +"New note type. 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 tags. 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\":\"…\"}."
      • changedInput schema / properties / text / description
        Previous value: -"Body text. Omit to leave unchanged."New value: +"New text, replacing the whole body. Omit to leave unchanged."
    • Changedupdate_person15 fields changed
      • changedInput schema / properties / addresses / description
        Previous value: -"Replace addresses. 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. Addresses: JSON array of Gramps address objects; or text blocks with lines like street:, city:, … (blank line or --- between addresses); or one plain line = street only. Grammar: gramps://input-guide."New value: +"Addresses. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Addresses: JSON array of Gramps address objects; or text blocks with lines like street:, city:, … (blank line or --- between addresses); or one plain line = street only. Grammar: gramps://input-guide."
      • changedInput schema / properties / alternateNames / description
        Previous value: -"Replace all alternate names. 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. Alternate names: array of strings (\"Married Name:: Jane|Smith\"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |)."New value: +"Alternate names. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Alternate names: array of strings (\"Married Name:: Jane|Smith\"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |)."
      • 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 / 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 all person–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: +"Events this person takes part in, with roles. In replace mode the list must hold every event the person keeps. 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 / familyHandles / description
        Previous value: -"Linked families where this person is parent/spouse. 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: +"Families where this person is a parent or spouse. 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 / handle / description
        Previous value: -"Person 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 person 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 / 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 / parentFamilyHandles / description
        Previous value: -"Linked parent (child-of) families. 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: +"Families where this person is a child. 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 / personAssociations / description
        Previous value: -"Linked person associations. 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. Person associations: JSON array of {ref, rel, ...}, or strings \"PERSON_HANDLE:: Godfather\" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide."New value: +"Associations with other people (godfather, friend, …). Omit to keep; applied per linkMode. Person associations (handles, not Gramps IDs): JSON array of {ref, rel, ...}, or strings \"PERSON_HANDLE:: Godfather\" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide."
      • changedInput schema / properties / primaryName / description
        Previous value: -"Replace primary name. Omit to leave unchanged. Name: full Gramps name JSON (see gramps://input-guide), a plain string (\"Married Name:: Jane|Smith\"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Plain full-name strings (name/text/full or \"Given Middle Surname\") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field."New value: +"New primary name; replaces the whole current one. Omit to leave unchanged. Name: full Gramps name JSON (see gramps://input-guide), a plain string (\"Married Name:: Jane|Smith\"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Custom, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Plain full-name strings (name/text/full or \"Given Middle Surname\") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field."
      • 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\":\"…\"}."
      • changedInput schema / properties / urls / description
        Previous value: -"Replace URLs. 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. URLs: JSON array of {type,path,desc}, or strings \"Web Home: https://…\" with optional \" — note\" after URL, or lines/| separated. Grammar: gramps://input-guide."New value: +"URLs. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. URLs: JSON array of {type,path,desc}, or strings \"Web Home: https://…\" with optional \" — note\" after URL, or lines/| separated. Grammar: gramps://input-guide."
    • Changedupdate_place17 fields changed
      • changedInput schema / properties / alternateNames / description
        Previous value: -"Replace alternate place names. 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. Alternate place names: array of strings (\"Old Name\" or \"Old Name::de\"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:\"New York\", date:\"1914-08-31-1924-01-26\"}] or date \"from 5 Jul 1944\". Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. Unrecognized dates fail validation (see get_reference(topic: \"input-guide\", section: \"dates\"))."New value: +"Alternate names. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Alternate place names: array of strings (\"Old Name\" or \"Old Name::de\"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:\"New York\", date:\"1914-08-31-1924-01-26\"}] or date \"from 5 Jul 1944\". Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. Unrecognized dates fail validation (see get_reference(topic: \"input-guide\", section: \"dates\"))."
      • changedInput schema / properties / citationHandles / description
        Previous value: -"Linked citations. 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 / code / description
        Previous value: -"Place code. Omit to leave unchanged."New value: +"New place code. Omit to leave unchanged."
      • changedInput schema / properties / enclosedBy / description
        Previous value: -"Linked parent place chain. 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. Parent place refs via enclosedBy (not enclosedByHandles): handle string, array of handles, JSON array of {ref, date?}, or shorthand \"HANDLE::1920-1950\" (date optional). Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. English months OK: \"HANDLE::from 1 Oct 1929 to 27 Sep 1937\". Examples: [{ref:\"…\", date:\"1708-1927\"}], \"HANDLE::1991-\", date \"1703-1914-08-31\". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: \"input-guide\", section: \"dates\")."New value: +"Places that contain this one. Omit to keep; applied per linkMode. Parent place refs via enclosedBy (not enclosedByHandles): handle or Gramps ID, array of them, JSON array of {ref, date?}, or shorthand \"HANDLE::1920-1950\" (date optional). Place dashes are spans (from…to); open \"1991-\" / \"from 1991\" are From. English months OK: \"HANDLE::from 1 Oct 1929 to 27 Sep 1937\". Examples: [{ref:\"…\", date:\"1708-1927\"}], \"HANDLE::1991-\", date \"1703-1914-08-31\". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: \"input-guide\", section: \"dates\")."
      • changedInput schema / properties / handle / description
        Previous value: -"Place 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 place 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 / lat / description
        Previous value: -"Latitude string. Omit to leave unchanged."New value: +"Latitude in decimal degrees, north positive (52.2297). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. Omit to keep the current value; pass an empty string to remove it."
      • removedInput schema / properties / lat / type
        Removed value: -[
        -  "string",
        -  "null"
        -]
      • changedInput schema / properties / lon / description
        Previous value: -"Longitude string. Omit to leave unchanged."New value: +"Longitude in decimal degrees, east positive (21.0122). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. Omit to keep the current value; pass an empty string to remove it."
      • removedInput schema / properties / lon / type
        Removed value: -[
        -  "string",
        -  "null"
        -]
      • changedInput schema / properties / mediaHandles / description
        Previous value: -"Linked media. 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 / name / description
        Previous value: -"Name text. Omit to leave unchanged."New value: +"New primary name. Omit to leave unchanged."
      • addedInput schema / properties / nameDate
        Added value: +{
        +  "default": null,
        +  "description": "When the primary name applies. Omit to keep the current date; pass an empty string to remove it. Gramps shows the first name, primary first, whose date is empty or matches the event date, so an undated primary name hides dated alternate names: date the primary name too (\"from 1937-02-10\"). Dashes are spans; open \"1991-\" / \"from 1991\" are From. Unreadable dates are rejected.",
        +  "type": [
        +    "string",
        +    "null"
        +  ]
        +}
      • changedInput schema / properties / nameLang / description
        Previous value: -"Language code for primary name. Omit to leave unchanged."New value: +"Language code of the primary name. Omit to leave unchanged."
      • changedInput schema / properties / noteHandles / description
        Previous value: -"Linked notes. 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 / placeType / description
        Previous value: -"Place type. 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: +"New place type. 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 tags. 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\":\"…\"}."
    • Changedupdate_repository8 fields changed
      • changedInput schema / properties / address / description
        Previous value: -"Street line (replaces address list when set). Omit to leave unchanged."New value: +"New postal address as one line; replaces every stored address, and an empty string removes them. Omit to leave unchanged."
      • changedInput schema / properties / handle / description
        Previous value: -"Repository 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 repository 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 / name / description
        Previous value: -"Name. Omit to leave unchanged."New value: +"New name. Omit to leave unchanged."
      • changedInput schema / properties / noteHandles / description
        Previous value: -"Linked notes. 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 / repoType / description
        Previous value: -"Type. 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: +"New type, e.g. Archive, Library, Church. 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 tags. 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\":\"…\"}."
      • changedInput schema / properties / url / description
        Previous value: -"Website URL (replaces url list when set). Omit to leave unchanged."New value: +"New website; replaces every stored link, and an empty string removes them. Omit to leave unchanged."
    • Changedupdate_source11 fields changed
      • changedInput schema / properties / abbrev / description
        Previous value: -"Abbreviation. Omit to leave unchanged."New value: +"New abbreviation. Omit to leave unchanged."
      • 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 / author / description
        Previous value: -"Author. Omit to leave unchanged."New value: +"New author. Omit to leave unchanged."
      • changedInput schema / properties / handle / description
        Previous value: -"Source 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 source 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. 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 / noteHandles / description
        Previous value: -"Linked notes. 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 / pubinfo / description
        Previous value: -"Publication info. Omit to leave unchanged."New value: +"New publication info. Omit to leave unchanged."
      • changedInput schema / properties / repositoryHandles / description
        Previous value: -"Repository refs. 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. Repository refs: JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. Multiple refs: JSON array or one multiline / |-separated string."New value: +"Repositories that hold the source. Omit to keep; applied per linkMode. Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings \"Ref : CallNumber : MediaType\". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: \"Ref : CallNumber\" and \"Ref :: MediaType\" are valid. Multiple refs: JSON array or one multiline / |-separated string."
      • changedInput schema / properties / tagHandles / description
        Previous value: -"Linked tags. 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\":\"…\"}."
      • changedInput schema / properties / title / description
        Previous value: -"Title. Omit to leave unchanged."New value: +"New title. Omit to leave unchanged."
  5. 30 tool updatesv2.2.0
    • First observedadd_event_to_person
    • First observedcreate_citation
    • First observedcreate_event
    • First observedcreate_family
    • First observedcreate_note
    • First observedcreate_person
    • First observedcreate_place
    • First observedcreate_repository
    • First observedcreate_source
    • First observedcreate_tag
    • First observeddelete_object
    • First observedget_bookmarks
    • First observedget_object
    • First observedget_person_tree
    • First observedget_recent_changes
    • First observedget_reference
    • First observedget_relations
    • First observedget_timeline
    • First observedlist_objects
    • First observedquick_add_person
    • First observedsearch
    • First observedupdate_citation
    • First observedupdate_event
    • First observedupdate_family
    • First observedupdate_media
    • First observedupdate_note
    • First observedupdate_person
    • First observedupdate_place
    • First observedupdate_repository
    • First observedupdate_source

TDQS

A4.2/5.0

Scored across 29 tools

Disambiguation4/5

Most tools target a distinct resource+action, and the descriptions actively disambiguate overlapping pairs (search vs list_objects, get_object vs list_objects vs search, get_relations vs get_person_tree vs get_timeline, read_media vs get_object). The nine per-type update_* tools are near-identical in prose and could blur together, but their target types keep them separable.

Naming Consistency4/5

Names follow a predictable verb_noun convention (create_person, update_event, list_objects, delete_object, get_object) across the whole set. The only deviation is read_media, which breaks the get_* pattern for reading an object, though it is deliberate and explained.

Tool Count3/5

At 29 tools this is heavy, and much of the bulk comes from nine create_* plus nine update_* tools that repeat nearly the same boilerplate per record type. The genealogy domain genuinely spans many record types, but a generic update/delete pattern would likely have sufficed, so the surface is borderline padded.

Completeness4/5

Coverage is strong: full create/update for every record type plus a generic delete_object with backlink handling, and read tools for search, listing, relations, trees, timelines and history. The notable gaps are the inability to create or upload media and to rename/delete tags through the server, which are documented limitations rather than oversights.

Maintenance

ActivityActive
ResponsivenessResponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to interact with Gramps genealogy databases for intelligent family tree research and management. Provides comprehensive tools for searching family data, creating records, analyzing relationships, and tracking genealogy research through natural language.
    45
    AGPL 3.0
  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI assistants to search, retrieve, and create genealogical records in a Gramps Web instance.
    6 npm
    4
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables MCP clients to read and edit a Gramps family tree hosted on Gramps Web, with guarded write operations that tag new records as unconfirmed for review.
    MIT