Gramps Web MCP
gramps-web-mcp
오픈소스 족보 플랫폼 Gramps Web을 위한 MCP 보조 서버입니다. AI 에이전트가 Model Context Protocol을 통해 가계도에 접근할 수 있도록 구조화된 도구 기반 인터페이스를 제공합니다.
이 프로젝트는 독립형 족보 UI나 Gramps Web을 대체하는 것이 아닙니다. 기존 Gramps Web 인스턴스와 함께 실행하세요. 사용자, 가계도, 미디어, 권한, 족보 편집 UI는 Gramps Web에 그대로 유지됩니다.
기능
57개의 MCP 도구 — 사람, 가족, 사건, 장소, 출처, 인용, 메모, 미디어, 저장소, 태그의 읽기/생성/수정/삭제 지원
검색 및 탐색 — 전체 텍스트 검색 및 페이지별 객체 목록 보기
친족 도구 — 조상, 후손, 관계, 타임라인
복합 워크플로우 — 빠른 사람 추가, 사람에 사건 추가, Gramps ID로 찾기
6개의 MCP 리소스 — 유형 어휘, 입력 가이드, 가계도 메타데이터, 이름 설정, 시각 인식 에이전트를 위한 옵트인 미디어 썸네일/파일
미디어 보호 장치 — 크기 제한, MIME 허용 목록, 비공개 레코드 기본값
MCP 프롬프트 — 연구, 사람/가족 추가, 가져오기를 위한 안내 워크플로우
다중 전송 방식 — stdio (로컬 클라이언트), Streamable HTTP, 레거시 SSE
읽기 전용 모드 — 모든 도구를 표시하면서 생성/수정/삭제 호출 차단
전체 목록은 도구 카탈로그를 참조하세요.
Related MCP server: ASPNET Core Debugging MCP Server
사전 요구 사항
.NET 8 SDK (로컬 개발용)
API 접근이 가능한 실행 중인 Gramps Web 인스턴스
Docker (선택 사항, 컨테이너 배포용)
빠른 시작
로컬 개발 (데모 서버)
run-local-server.sh는 공개 demo.grampsweb.org 인스턴스에 잘 알려진 데모 자격 증명(owner / owner)을 사용하여 연결합니다:
./run-local-server.sh서버는 HTTP 전송 방식으로 http://127.0.0.1:8080/mcp에서 시작됩니다. 루프백 전용으로 바인딩할 때는 API 키가 필요하지 않습니다.
Docker
사전 빌드된 멀티 아키텍처 이미지(linux/amd64, linux/arm64)가 GitHub Container Registry에 게시됩니다. Docker가 자동으로 일치하는 아키텍처를 선택합니다. amd64는 대부분의 Unraid 및 x86 호스트를, arm64는 Apple Silicon 및 ARM SBC를 지원합니다:
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이미지는 Docker HEALTHCHECK, Unraid 컨테이너 상태 확인 및 기타 가동 시간 모니터를 위한 GET /health 엔드포인트를 노출합니다. MCP 서버가 Gramps Web에 대해 인증할 수 있으면 HTTP 200을 반환하고, 그렇지 않으면 HTTP 503을 반환합니다. 기본 공개 응답은 최소화되어 있습니다: { "status": "healthy" } 또는 { "status": "unhealthy" }. 시작 로그에는 API에 연결할 수 있게 되면 Connected to Gramps Web at …과 같은 줄이 포함됩니다.
이미지는 기본적으로 포트 8080에서 Streamable HTTP(MCP_TRANSPORT=http)를 사용하며, 위 명령어에서 사용된 방식입니다. 컨테이너를 직접 실행하는 클라이언트(예: MCP Registry 설치)는 대신 -e MCP_TRANSPORT=stdio와 함께 stdin을 열린 상태로 유지하여(docker run -i) stdio로 실행합니다. 이는 server.json에 선언된 모드입니다.
읽기 전용 모드의 경우 -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:latestUnraid 설치
Unraid 사용자는 Community Applications에서 gramps-web-mcp를 설치할 수 있습니다. 템플릿 소스는
Scormave/gramps-web-mcp-unraid에서 관리됩니다.
Unraid 관련 도움말은 Unraid 포럼 지원 스레드를 참조하세요.
기본 설정:
Unraid에서 Apps / Community Applications를 엽니다.
gramps-web-mcp를 검색하고 템플릿을 설치합니다.Gramps Web 인스턴스에 맞게
GRAMPS_API_URL,GRAMPS_USERNAME,GRAMPS_PASSWORD,GRAMPS_TREE_ID를 설정합니다. MCP 포트가 네트워크의 다른 머신에서 접근 가능한 경우MCP_API_KEY를 설정합니다.기본 컨테이너 포트
8080을 유지하거나 다른 호스트 포트로 매핑합니다.컨테이너를 시작하고
/health를 확인합니다. 서비스가 Gramps Web에 인증할 수 있으면 HTTP 200을 반환하며, 기본적으로 최소 JSON 응답이 반환됩니다.
가장 쉬운 연결을 위해 Gramps Web과 gramps-web-mcp를 동일한 Unraid Docker 네트워크에서 실행하고 GRAMPS_API_URL을 Gramps Web 컨테이너 URL로 설정하세요. 클라이언트를 위한 MCP 엔드포인트는 http://<unraid-host>:<mapped-port>/mcp입니다.
Gramps Web + MCP (Docker Compose)
동일한 호스트 및 Docker 네트워크에서 Gramps Web과 MCP 서버를 실행하려면 docker-compose.example.yml을 시작점으로 사용하세요:
cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -dGramps Web은 포트 5055에, MCP는 포트 8080에 게시됩니다(/mcp 및 /health). Compose 네트워크 내에서 MCP 컨테이너는 http://grampsweb:5000에서 Gramps Web에 접근합니다.
Claude Desktop (MCPB 확장)
Claude Desktop용 원클릭 설치는 GitHub Releases에서 MCP Bundle (.mcpb)로 제공됩니다. 플랫폼에 맞는 번들을 다운로드하세요:
플랫폼 | 아티팩트 |
macOS Apple Silicon |
|
macOS Intel |
|
Windows x64 |
|
Linux x64 |
|
Linux ARM64 |
|
최신 릴리스에서 해당 OS의
.mcpb파일을 다운로드합니다.더블 클릭하거나 Claude Desktop 창으로 드래그합니다.
Gramps Web URL, 사용자 이름, 비밀번호/토큰, 가계도 UUID를 입력합니다.
첫 번째 세션에서는 읽기 전용 모드를 활성화한 상태로 유지합니다. Claude가 레코드를 생성하거나 편집하도록 하려는 경우에만 비활성화합니다.
설치를 완료하고 새 채팅을 시작합니다.
확장은 로컬에서 stdio를 통해 실행되며, 머신에 .NET SDK가 필요하지 않습니다.
패키징 세부 사항은 mcpb/README.md를, 개인정보 보호 정책은 PRIVACY.md를 참조하세요.
로컬에서 번들을 빌드하려면:
./scripts/pack-mcpb.sh osx-arm64 # or osx-x64, win-x64, linux-x64, linux-arm64MCP 클라이언트 구성 (수동)
stdio (예: 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"
}
}
}
}읽기 전용 모드로 stdio 서버를 실행하려면 env에 "GRAMPS_READ_ONLY": "true"를 추가하세요.
HTTP (원격 / Docker):
MCP 클라이언트를 http://host:8080/mcp로 Streamable HTTP 전송 방식으로 지정하세요.
MCP_API_KEY가 설정된 경우, 모든 MCP 요청에 Authorization: Bearer <key> 또는 X-Api-Key: <key>로 전송하세요.
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}'시각 인식 에이전트는 도구(GetMediaThumbnail, GetMediaFile) 또는 바이너리 MCP 리소스(예: gramps://media/{handle}/thumbnail/{size}, gramps://media/{handle}/file)를 통해 옵트인 미디어를 읽을 수 있습니다. GetMediaFile은 MIME 유형에 따라 이미지, 오디오 또는 임베디드 blob 리소스 콘텐츠를 반환합니다. 종단 간 분석은 MCP 클라이언트가 입력된 도구 콘텐츠 또는 바이너리 리소스 콘텐츠를 적절한 모델에 전달하는지에 따라 달라집니다.
구성
필수 (Gramps 연결)
변수 | 설명 |
| Gramps Web 인스턴스의 기본 URL (끝에 슬래시 없음) |
| API 사용자 이름 |
| API 비밀번호 또는 토큰 |
| 해당 서버의 가계도 UUID |
런타임 모드
변수 | 기본값 |
|
|
|
|
|
|
GRAMPS_READ_ONLY:true로 설정하면 도구는 표시되지만 생성/수정/삭제 호출을 차단합니다.GRAMPS_MUTATION_SERIALIZE: 이 프로세스에서 생성/수정/삭제 HTTP 호출을 한 번에 하나씩 실행합니다.GRAMPS_MUTATION_MIN_INTERVAL_MS: 복합 도구 내 단계를 포함한 변경 HTTP 호출 간 최소 대기 시간입니다.
런타임 참고 사항:
GRAMPS_READ_ONLY=false는 서버가 읽기/쓰기 모드로 시작됨을 의미합니다.Claude Desktop MCPB 확장은 예외입니다. 설정 폼이 기본적으로 읽기 전용으로 설정되어 더 안전하게 처음 사용할 수 있습니다.
쓰기 직렬화와 선택적 간격은 일반적인 Gramps Web SQLite 가계도를 에이전트의 쓰기 폭주로부터 보호합니다.
쓰기 게이트는 프로세스 내에서만 작동합니다. 여러 MCP 복제본, Gramps Web UI 또는 다른 API 클라이언트와 조정하지 않습니다.
순차 편집 시에도
database is locked오류가 발생하는 SQLite 배포의 경우GRAMPS_MUTATION_MIN_INTERVAL_MS=250또는500으로 설정하세요.SQLite 잠금 오류 또는 상위 HTTP 429 발생 시, 변경 도구는 일반 500 대신 짧은 백오프 힌트와 함께 재시도 가능한 MCP 오류를 반환합니다.
Gramps Web이 PostgreSQL을 사용하고 병렬 쓰기를 원하는 경우
GRAMPS_MUTATION_SERIALIZE=false로 설정하세요.
미디어 파일 접근
미디어 바이트 도구/리소스는 기본적으로 비활성화되어 있습니다. get_media는 파일 다운로드 없이 메타데이터에 계속 사용할 수 있습니다.
변수 | 설명 | 기본값 |
| 썸네일 및 전체 파일에 대한 바이너리 미디어 도구/리소스를 활성화합니다. |
|
| 모든 미디어 리소스에서 반환되는 최대 바이트 수 |
|
| 미디어 바이트에 허용되는 MIME 유형 | 아래 참조 |
| 비공개로 표시된 Gramps 미디어 레코드의 바이트를 허용합니다. |
|
AI 분석에는 GetMediaThumbnail 또는 gramps://media/{handle}/thumbnail/{size}를 선호하세요. 전체 파일은 크고 민감할 수 있으며, 동일한 크기, MIME, 비공개 레코드 검사가 적용됩니다.
정확한 유형과 type/* 와일드카드가 지원됩니다. 기본 미디어 허용 목록은 image/jpeg,image/png,image/webp,image/avif,application/pdf입니다.
전송 방식
GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD, GRAMPS_TREE_ID는 평소와 같이 설정하세요.
값 | 동작 |
(설정 안 함 또는 | stdin/stdout을 통한 JSON-RPC (기본값; 로컬 클라이언트). |
|
|
| 레거시 MCP SSE: |
HTTP 전송 방식의 경우 응답이 SSE를 통해 스트리밍됩니다. 프로토콜 세부 사항은 Streamable HTTP 명세를 참조하세요. ASPNETCORE_URLS를 설정하여 수신 주소를 선택하세요. 예: http://127.0.0.1:8080.
선택 사항 (MCP 전송)
Variable | Description | Default |
| HTTP/SSE용 수신 대기 URL | — |
| MCP 엔드포인트의 URL 접두사 |
|
| Streamable HTTP용 무상태 모드 |
|
|
|
|
| HTTP/SSE 전송용 공유 비밀 키(순환을 위해 쉼표로 구분, 최소 16자) | — |
HTTP 인증
MCP_API_KEY가 설정되면 모든 MCP HTTP/SSE 엔드포인트는 모든 요청에서 키를 요구합니다.
GET /health는 Docker 및 로드 밸런서 프로브를 위해 익명으로 유지됩니다.
키 생성:
openssl rand -base64 32키가 없어도 서버는 계속 시작됩니다(하위 호환). 수신 대기 주소가 루프백 전용이 아닌 경우
MCP_API_KEY를 설정하거나, 자체 인증이 있는 역방향 프록시를 사용하거나, 로컬 전용으로
127.0.0.1에 바인딩할 것을 권장하는 경고가 기록됩니다.
Docker 내부에서 ASPNETCORE_URLS는 일반적으로 http://0.0.0.0:8080이므로
호스트가 127.0.0.1에서만 포트를 게시하더라도 경고가 표시됩니다.
외부 접근이 이미 제한된 경우에는 예상되는 동작입니다.
개발
dotnet testCONTRIBUTING.md 및 개발자 가이드를 참조하세요.
문서
문서 | 설명 |
모든 문서 파일 | |
전체 MCP 도구 참조 자료 | |
데스크톱 확장 프로그램 패키징 | |
데스크톱 확장 프로그램의 데이터 처리 | |
MCP 클라이언트용 권장 프롬프트 | |
시스템 설계 개요 |
기여
기여를 환영합니다. CONTRIBUTING.md를 참조하세요.
보안
취약점을 신고하려면 SECURITY.md를 참조하세요.
개인정보 처리방침
Claude Desktop 확장 프로그램은 로컬 MCP 서버입니다. 사용자가 구성한 Gramps Web 인스턴스에만 데이터를 전송하며 분석 데이터나 대화 데이터를 수집하지 않습니다. 자세한 내용은 PRIVACY.md를 참조하세요.
라이선스
Copyright (c) Scormave
이 프로젝트는 GNU Affero General Public License v3.0 (AGPL-3.0-or-later)에 따라 라이선스가 부여됩니다. 이 소프트웨어는 네트워크 서버 소프트웨어이므로, 수정된 버전을 호스팅하는 경우 네트워크를 통해 상호작용하는 사용자에게 해당 소스 코드를 제공해야 합니다.
Available Tools
29 toolscreate_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").
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 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. | |
| page | No | 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. | |
| isPrivate | No | Mark the citation private (default false). | |
| attributes | No | 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. | |
| confidence | No | How reliable the cited record is: Very Low, Low, Normal (default), High or Very High. | Normal |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes, 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":"…"}. | |
| mediaHandles | No | 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":"…"}. | |
| sourceHandle | Yes | The 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").
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 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. | |
| eventType | Yes | 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"). | |
| isPrivate | No | Mark the event private (default false). | |
| attributes | No | Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| description | No | Short description, optional. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| placeHandle | No | 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. | |
| mediaHandles | No | Media. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| citationHandles | No | 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":"…"}. |
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").
| Name | Required | Description | Default |
|---|---|---|---|
| childRefs | No | 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.). | |
| eventRefs | No | 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). | |
| isPrivate | No | Mark the family private (default false). | |
| attributes | No | Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| fatherHandle | No | The father, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| mediaHandles | No | Media. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| motherHandle | No | The mother, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| citationHandles | No | Citations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| relationshipType | No | Relationship type: Married (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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The note text (required). | |
| format | No | Text format: Plain (default) or Html. | Plain |
| noteType | No | 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"). | General |
| isPrivate | No | Mark the note private (default false). | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |
TDQS
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.
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.
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.
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.
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.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| urls | No | 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. | |
| gender | No | Gender: Female, Male, or Unknown (default Unknown). | Unknown |
| addresses | No | 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. | |
| eventRefs | No | 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). | |
| isPrivate | No | Mark the person private (default false). | |
| attributes | No | Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| primaryName | Yes | 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. | |
| mediaHandles | No | Media. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| familyHandles | No | 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":"…"}. | |
| alternateNames | No | 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 |). | |
| citationHandles | No | Citations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| personAssociations | No | 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. | |
| parentFamilyHandles | No | 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":"…"}. |
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").
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in decimal degrees, north positive (52.2297). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. | |
| lon | No | Longitude in decimal degrees, east positive (21.0122). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. | |
| code | No | Place code or postal code (optional). | |
| name | Yes | Primary name (required). | |
| nameDate | No | 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. | |
| nameLang | No | Language code of the primary name, e.g. pl or de (optional). | |
| isPrivate | No | Mark the place private (default false). | |
| placeType | No | 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"). | |
| enclosedBy | No | 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"). | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | Media. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| alternateNames | No | 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")). | |
| citationHandles | No | Citations. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Website, e.g. https://archive.example.org, stored as the repository's web home link (optional). | |
| name | Yes | Name, e.g. "State Archive in Warsaw" (required). | |
| address | No | Postal address as one line, e.g. "12 High Street, London", stored as the street of the repository's address (optional). | |
| repoType | No | 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"). | |
| isPrivate | No | Mark the repository private (default: false); Gramps Web hides private records from users not allowed to see them. | |
| tagHandles | No | 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":"…"}. | |
| noteHandles | No | 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":"…"}. |
TDQS
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.
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.
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.
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.
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.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title (required). | |
| abbrev | No | Short title for lists (optional). | |
| author | No | Author or issuing body (optional). | |
| pubinfo | No | Publication info: publisher, place, year (optional). | |
| isPrivate | No | Mark the source private (default false). | |
| attributes | No | 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. | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | Media. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| repositoryHandles | No | 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. |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tag name shown on records (required). | |
| color | No | Color as six hex digits RRGGBB without #, e.g. FF5733; stored as given. Default 000000 (black). | 000000 |
| priority | No | Sort priority among tags in Gramps (default 0). |
TDQS
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.
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.
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.
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.
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.
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 ObjectADestructive
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.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | true deletes even when other records still point to it, leaving those links dangling (default false). | |
| handle | Yes | The record to delete. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| objectType | Yes | Record type: person, family, event, place, source, citation, note, media, repository or tag. |
TDQS
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.
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.
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.
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.
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.
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 BookmarksARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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 ObjectARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| extended | No | 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. | |
| identifier | Yes | 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. | |
| objectType | No | Record type: person, family, event, place, source, citation, note, media, repository or tag. Omit for a Gramps ID; required for a handle. |
TDQS
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.
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.
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.
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.
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.
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 TreeARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| person | Yes | The person to start from. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| direction | Yes | ancestors (parents, grandparents, …) or descendants (children, grandchildren, …). | |
| generations | No | How many generations to walk, 1–10 (default 3); other values are clamped. | |
| kinshipLabels | No | When true (default), add kinship text such as Father's mother or Granddaughter. When false, show only generation numbers. |
TDQS
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.
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.
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.
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.
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.
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 ChangesARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many transactions to show, 1–100 (default 20); other values are clamped. |
TDQS
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.
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.
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.
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.
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.
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 ReferenceARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Which reference: input-guide, types, metadata or name-settings. | |
| section | No | 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. |
TDQS
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.
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.
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.
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.
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.
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 RelationsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| handle1 | Yes | 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. | |
| handle2 | Yes | 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. |
TDQS
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.
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.
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.
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.
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.
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 TimelineARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| dates | No | Only 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. | |
| events | No | Only these event categories (omit for all): vital, family, religious, vocational, academic, travel, legal, residence, other, custom. | |
| relatives | No | Person timelines only: whose events to add: father, mother, brother, sister, wife, husband, son, daughter. | |
| identifier | Yes | The person, family or place. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| objectType | Yes | Whose timeline: person, family or place. | |
| relativeEvents | No | Person timelines only: event categories to show for those relatives, same values as events. |
TDQS
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.
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.
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.
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.
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.
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 ObjectsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| gql | No | Filter in Gramps Query Language, run on the server, e.g. gender == 1 or media_list.length >= 1 (optional). | |
| page | No | Page number, from 1 (default 1). | |
| sort | No | Field to sort by, e.g. gramps_id; a leading - sorts descending, e.g. -change for latest edits first (optional). | |
| grampsId | No | Only the record with this Gramps ID, e.g. I0001 (not a handle; optional). | |
| pagesize | No | Records per page, 1–100 (default 20). | |
| objectType | Yes | Which records to list: people, families, events, places, sources, citations, repositories, notes, media or tags. | |
| sourceHandle | No | 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. |
TDQS
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.
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.
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.
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.
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.
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 MediaARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Download mode: thumbnail | file. Default thumbnail. Use file only when a preview is insufficient. | thumbnail |
| size | No | Thumbnail 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. | |
| handle | Yes | The media object to show. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. |
TDQS
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.
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.
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.
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.
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.
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.
searchSearchARead-only
Find records by words in them: one query across people, families, events, places, sources, citations, repositories, notes, media and tags. Start here when you have a name, place, title or other text but no Gramps ID. Returns one line per hit (type, Gramps ID, summary, handle) with the page and total count; pass a Gramps ID or handle to get_object for the full record. To browse or filter one type by its fields (all people, citations of one source, sorted by change) use list_objects. Very long queries can fail on the server; use a shorter term then.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). | |
| query | Yes | Words to find; * matches any ending. Examples: Smith*, John, Dublin*, a register title. | |
| pagesize | No | Hits per page, 1–100 (default 20). |
TDQS
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. The description adds genuinely useful behavioral context beyond that: the per-hit return shape (type, Gramps ID, summary, handle), page/total count, and the server-side failure mode for very long queries with a workaround. It stops short of pagination limits or performance notes, so not a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then routing, then return shape, then the alternative tool, then the failure caveat. Every sentence earns its place and the ordering matches how an agent decides and invokes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 explains the return format, count, and the handoff to get_object for full records, plus a real operational caveat. Nothing needed to call this search tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so query, page and pagesize are already documented (including the '*' wildcard and ranges). The description only marginally reinforces query semantics via the long-query advice; baseline 3 is correct when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (records across ten named entity types) and explicitly distinguishes itself from siblings get_object and list_objects. An agent can tell exactly what this tool does and does not cover 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit entry condition ("Start here when you have a name, place, title or other text but no Gramps ID") and names the alternative with its selecting condition ("To browse or filter one type by its fields ... use list_objects"). When-to-use and when-to-use-something-else are both stated.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 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. | |
| page | No | 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. | |
| handle | Yes | The citation to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. Each attribute takes only type, value and private. | |
| confidence | No | New confidence: Very Low, Low, Normal, High or Very High. Omit to leave unchanged. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | 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":"…"}. | |
| sourceHandle | No | 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. |
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").
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 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. | |
| handle | Yes | The event to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| eventType | No | 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"). | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| description | No | New description. Omit to leave unchanged. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| placeHandle | No | New place. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| mediaHandles | No | Media. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| citationHandles | No | Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |
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").
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | The family to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| childRefs | No | Children with their relations to the parents. In replace mode the list must hold every child the family keeps. Omit to keep; applied per linkMode. Child references (handles, not Gramps IDs): JSON array of {ref, frel, mrel}, strings "HANDLE::RelType" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. A relation must be a standard Gramps one (Birth, Adopted, Stepchild, Sponsored, Foster, Unknown, None) or a custom one the tree already uses. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.). | |
| eventRefs | No | Family events (Marriage, Divorce, …). Omit to keep; applied per linkMode. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings "HANDLE::Role" (default role: Primary), comma/pipe/newline-separated, or a single handle. A role must be a standard Gramps role or a custom one the tree already uses; anything else is rejected with suggestions. JSON objects accept snake_case or camelCase list fields (note_list / noteList). | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| sortEvents | No | 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). | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| fatherHandle | No | New father. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| mediaHandles | No | Media. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| motherHandle | No | New mother. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| citationHandles | No | Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| relationshipType | No | Relationship type (Married, Unmarried, Civil Union, Unknown). Omit to leave unchanged. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: "types"). |
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").
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 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. | |
| handle | Yes | The media object to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| description | No | New description (caption). Omit to leave unchanged. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| citationHandles | No | Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | 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. | |
| format | No | Plain or Html. Omit to leave unchanged. | |
| handle | Yes | The note to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| noteType | No | 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"). | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |
TDQS
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.
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.
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.
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.
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.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| urls | No | 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. | |
| gender | No | Gender: Female, Male, or Unknown. Omit to leave unchanged. | |
| handle | Yes | The person to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| addresses | No | 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. | |
| eventRefs | No | 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). | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| sortEvents | No | 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). | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| primaryName | No | 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. | |
| mediaHandles | No | 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":"…"}. | |
| familyHandles | No | 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":"…"}. | |
| alternateNames | No | 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 |). | |
| citationHandles | No | Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| personAssociations | No | 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. | |
| parentFamilyHandles | No | 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":"…"}. |
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").
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | 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. | |
| lon | No | 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. | |
| code | No | New place code. Omit to leave unchanged. | |
| name | No | New primary name. Omit to leave unchanged. | |
| handle | Yes | The place to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| nameDate | No | 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. | |
| nameLang | No | Language code of the primary name. Omit to leave unchanged. | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| placeType | No | 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"). | |
| enclosedBy | No | 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"). | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | 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":"…"}. | |
| alternateNames | No | 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")). | |
| citationHandles | No | Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | New website; replaces every stored link, and an empty string removes them. Omit to leave unchanged. | |
| name | No | New name. Omit to leave unchanged. | |
| handle | Yes | The repository to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| address | No | New postal address as one line; replaces every stored address, and an empty string removes them. Omit to leave unchanged. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| repoType | No | 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"). | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |
TDQS
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.
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.
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.
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.
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.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | New title. Omit to leave unchanged. | |
| abbrev | No | New abbreviation. Omit to leave unchanged. | |
| author | No | New author. Omit to leave unchanged. | |
| handle | Yes | The source to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| pubinfo | No | New publication info. Omit to leave unchanged. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. Each attribute takes only type, value and private. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | 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":"…"}. | |
| repositoryHandles | No | 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. |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v2.3.2- Changed
create_citation1 field changed- changed
Input schema / properties / attributes / descriptionPrevious 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."
- Changed
create_event1 field changed- changed
Input schema / properties / attributes / descriptionPrevious 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."
- Changed
create_family3 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / childRefs / descriptionPrevious 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.)." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)."
- Changed
create_person5 fields changed- changed
Input schema / properties / alternateNames / descriptionPrevious 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 |)." - changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - changed
Input schema / properties / primaryName / descriptionPrevious 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." - changed
Input schema / properties / urls / descriptionPrevious 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."
- Changed
create_source2 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / repositoryHandles / descriptionPrevious 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."
- Changed
update_citation1 field changed- changed
Input schema / properties / attributes / descriptionPrevious 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."
- Changed
update_event1 field changed- changed
Input schema / properties / attributes / descriptionPrevious 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."
- Changed
update_family4 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / childRefs / descriptionPrevious 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.)." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - added
Input schema / properties / sortEventsAdded 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" +}
- Changed
update_media1 field changed- changed
Input schema / properties / attributes / descriptionPrevious 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."
- Changed
update_person6 fields changed- changed
Input schema / properties / alternateNames / descriptionPrevious 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 |)." - changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - changed
Input schema / properties / primaryName / descriptionPrevious 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." - added
Input schema / properties / sortEventsAdded 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" +} - changed
Input schema / properties / urls / descriptionPrevious 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."
- Changed
update_source2 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / repositoryHandles / descriptionPrevious 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."
1 tool update
- Added
read_media
11 tool updates
v2.3.1- Changed
create_citation3 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - removed
Input schema / properties / textRemoved value: -{ - "default": null, - "description": "Citation text or transcript (optional).", - "type": [ - "string", - "null" - ] -}
- Changed
create_source1 field changed- changed
Input schema / properties / attributes / descriptionPrevious 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."
- Changed
update_citation3 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / linkMode / descriptionPrevious 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." - removed
Input schema / properties / textRemoved value: -{ - "default": null, - "description": "New citation text or transcript. Omit to leave unchanged.", - "type": [ - "string", - "null" - ] -}
- Changed
update_event1 field changed- changed
Input schema / properties / linkMode / descriptionPrevious 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."
- Changed
update_family1 field changed- changed
Input schema / properties / linkMode / descriptionPrevious 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."
- Changed
update_media1 field changed- changed
Input schema / properties / linkMode / descriptionPrevious 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."
- Changed
update_note2 fields changed- changed
Input schema / properties / linkMode / descriptionPrevious 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." - changed
Input schema / properties / text / descriptionPrevious 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."
- Changed
update_person1 field changed- changed
Input schema / properties / linkMode / descriptionPrevious 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."
- Changed
update_place1 field changed- changed
Input schema / properties / linkMode / descriptionPrevious 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."
- Changed
update_repository1 field changed- changed
Input schema / properties / linkMode / descriptionPrevious 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."
- Changed
update_source2 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / linkMode / descriptionPrevious 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."
29 tool updates
v2.3.0- Removed
add_event_to_person - Changed
create_citation9 fields changed- changed
Input schema / properties / confidence / descriptionPrevious 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." - changed
Input schema / properties / date / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark record private (default: false)"New value: +"Mark the citation private (default false)." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / page / descriptionPrevious 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." - changed
Input schema / properties / sourceHandle / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / text / descriptionPrevious value: -"Citation text / transcript (optional)"New value: +"Citation text or transcript (optional)."
- Changed
create_event9 fields changed- changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / date / descriptionPrevious 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." - changed
Input schema / properties / description / descriptionPrevious value: -"Event description (optional)"New value: +"Short description, optional." - changed
Input schema / properties / eventType / descriptionPrevious 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\")." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark record private (default: false)"New value: +"Mark the event private (default false)." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / placeHandle / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
create_family10 fields changed- changed
Input schema / properties / childRefs / descriptionPrevious 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.)." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - changed
Input schema / properties / fatherHandle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark record private (default: false)"New value: +"Mark the family private (default false)." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / motherHandle / descriptionPrevious 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." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / relationshipType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
create_note5 fields changed- changed
Input schema / properties / format / descriptionPrevious value: -"Text format: Plain or Html (default: Plain)"New value: +"Text format: Plain (default) or Html." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark as private (optional)"New value: +"Mark the note private (default false)." - changed
Input schema / properties / noteType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / text / descriptionPrevious value: -"Note body text (required)."New value: +"The note text (required)."
- Changed
create_person9 fields changed- changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - changed
Input schema / properties / familyHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark record as private (default: false)"New value: +"Mark the person private (default false)." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / parentFamilyHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / personAssociations / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
create_place16 fields changed- changed
Input schema / properties / alternateNames / descriptionPrevious 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\"))." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / code / descriptionPrevious value: -"Place code / postal reference (optional)"New value: +"Place code or postal code (optional)." - changed
Input schema / properties / enclosedBy / descriptionPrevious 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\")." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark record private (default: false)"New value: +"Mark the place private (default false)." - changed
Input schema / properties / lat / descriptionPrevious 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." - removed
Input schema / properties / lat / typeRemoved value: -[ - "string", - "null" -] - changed
Input schema / properties / lon / descriptionPrevious 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." - removed
Input schema / properties / lon / typeRemoved value: -[ - "string", - "null" -] - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / name / descriptionPrevious value: -"Primary display name (required)."New value: +"Primary name (required)." - added
Input schema / properties / nameDateAdded 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" + ] +} - changed
Input schema / properties / nameLang / descriptionPrevious value: -"Language code for primary name (default: omitted)"New value: +"Language code of the primary name, e.g. pl or de (optional)." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / placeType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
create_repository7 fields changed- changed
Input schema / properties / address / descriptionPrevious 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)." - changed
Input schema / properties / isPrivate / descriptionPrevious 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." - changed
Input schema / properties / name / descriptionPrevious value: -"Name (required)."New value: +"Name, e.g. \"State Archive in Warsaw\" (required)." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / repoType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / url / descriptionPrevious value: -"Website URL (optional)"New value: +"Website, e.g. https://archive.example.org, stored as the repository's web home link (optional)."
- Changed
create_source8 fields changed- changed
Input schema / properties / abbrev / descriptionPrevious value: -"Abbreviation (optional)"New value: +"Short title for lists (optional)." - changed
Input schema / properties / author / descriptionPrevious value: -"Author name (optional)"New value: +"Author or issuing body (optional)." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Mark record private (default: false)"New value: +"Mark the source private (default false)." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / pubinfo / descriptionPrevious value: -"Publication info (optional)"New value: +"Publication info: publisher, place, year (optional)." - changed
Input schema / properties / repositoryHandles / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
create_tag3 fields changed- changed
Input schema / properties / color / descriptionPrevious 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)." - changed
Input schema / properties / name / descriptionPrevious value: -"Display name (required)."New value: +"Tag name shown on records (required)." - changed
Input schema / properties / priority / descriptionPrevious value: -"Sort priority; lower often sorts first (default 0)."New value: +"Sort priority among tags in Gramps (default 0)."
- Changed
delete_object3 fields changed- changed
Input schema / properties / force / descriptionPrevious 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)." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / objectType / descriptionPrevious 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."
- Changed
get_object3 fields changed- changed
Input schema / properties / extended / descriptionPrevious 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." - changed
Input schema / properties / identifier / descriptionPrevious 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." - changed
Input schema / properties / objectType / descriptionPrevious 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."
- Changed
get_person_tree3 fields changed- changed
Input schema / properties / direction / descriptionPrevious value: -"Tree direction: ancestors | descendants."New value: +"ancestors (parents, grandparents, …) or descendants (children, grandchildren, …)." - changed
Input schema / properties / generations / descriptionPrevious 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." - changed
Input schema / properties / person / descriptionPrevious 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."
- Changed
get_recent_changes1 field changed- changed
Input schema / properties / limit / descriptionPrevious 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."
- Changed
get_reference2 fields changed- changed
Input schema / properties / section / descriptionPrevious 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." - changed
Input schema / properties / topic / descriptionPrevious value: -"Reference topic: input-guide | types | metadata | name-settings."New value: +"Which reference: input-guide, types, metadata or name-settings."
- Changed
get_relations2 fields changed- changed
Input schema / properties / handle1 / descriptionPrevious 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." - changed
Input schema / properties / handle2 / descriptionPrevious 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."
- Changed
get_timeline5 fields changed- changed
Input schema / properties / events / descriptionPrevious 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." - changed
Input schema / properties / identifier / descriptionPrevious 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." - changed
Input schema / properties / objectType / descriptionPrevious value: -"Timeline owner type: person | family | place."New value: +"Whose timeline: person, family or place." - changed
Input schema / properties / relativeEvents / descriptionPrevious 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." - changed
Input schema / properties / relatives / descriptionPrevious 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."
- Changed
list_objects7 fields changed- changed
Input schema / properties / gql / descriptionPrevious 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)." - changed
Input schema / properties / grampsId / descriptionPrevious 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)." - changed
Input schema / properties / objectType / descriptionPrevious 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." - changed
Input schema / properties / page / descriptionPrevious value: -"1-based page. Default 1."New value: +"Page number, from 1 (default 1)." - changed
Input schema / properties / pagesize / descriptionPrevious value: -"Page size. Default 20, max 100."New value: +"Records per page, 1–100 (default 20)." - changed
Input schema / properties / sort / descriptionPrevious 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)." - changed
Input schema / properties / sourceHandle / descriptionPrevious 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."
- Removed
quick_add_person - Changed
search3 fields changed- changed
Input schema / properties / page / descriptionPrevious value: -"1-based page index. Default 1."New value: +"Page number, from 1 (default 1)." - changed
Input schema / properties / pagesize / descriptionPrevious value: -"Page size. Default 20, maximum 100."New value: +"Hits per page, 1–100 (default 20)." - changed
Input schema / properties / query / descriptionPrevious value: -"Query string; * is wildcard. Examples: Smith*, John, Dublin*"New value: +"Words to find; * matches any ending. Examples: Smith*, John, Dublin*, a register title."
- Changed
update_citation11 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / confidence / descriptionPrevious 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." - changed
Input schema / properties / date / descriptionPrevious 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." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / page / descriptionPrevious 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." - changed
Input schema / properties / sourceHandle / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / text / descriptionPrevious value: -"Transcript or citation text. Omit to leave unchanged."New value: +"New citation text or transcript. Omit to leave unchanged."
- Changed
update_event11 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / date / descriptionPrevious 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." - changed
Input schema / properties / description / descriptionPrevious value: -"Description text. Omit to leave unchanged."New value: +"New description. Omit to leave unchanged." - changed
Input schema / properties / eventType / descriptionPrevious 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\")." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / placeHandle / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
update_family12 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / childRefs / descriptionPrevious 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.)." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - changed
Input schema / properties / fatherHandle / descriptionPrevious 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." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / motherHandle / descriptionPrevious 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." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / relationshipType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
update_media8 fields changed- changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / date / descriptionPrevious 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." - changed
Input schema / properties / description / descriptionPrevious value: -"Description. Omit to leave unchanged."New value: +"New description (caption). Omit to leave unchanged." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
update_note5 fields changed- changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / noteType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / text / descriptionPrevious value: -"Body text. Omit to leave unchanged."New value: +"New text, replacing the whole body. Omit to leave unchanged."
- Changed
update_person15 fields changed- changed
Input schema / properties / addresses / descriptionPrevious 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." - changed
Input schema / properties / alternateNames / descriptionPrevious 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 |)." - changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / eventRefs / descriptionPrevious 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)." - changed
Input schema / properties / familyHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / parentFamilyHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / personAssociations / descriptionPrevious 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." - changed
Input schema / properties / primaryName / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / urls / descriptionPrevious 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."
- Changed
update_place17 fields changed- changed
Input schema / properties / alternateNames / descriptionPrevious 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\"))." - changed
Input schema / properties / citationHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / code / descriptionPrevious value: -"Place code. Omit to leave unchanged."New value: +"New place code. Omit to leave unchanged." - changed
Input schema / properties / enclosedBy / descriptionPrevious 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\")." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / lat / descriptionPrevious 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." - removed
Input schema / properties / lat / typeRemoved value: -[ - "string", - "null" -] - changed
Input schema / properties / lon / descriptionPrevious 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." - removed
Input schema / properties / lon / typeRemoved value: -[ - "string", - "null" -] - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / name / descriptionPrevious value: -"Name text. Omit to leave unchanged."New value: +"New primary name. Omit to leave unchanged." - added
Input schema / properties / nameDateAdded 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" + ] +} - changed
Input schema / properties / nameLang / descriptionPrevious value: -"Language code for primary name. Omit to leave unchanged."New value: +"Language code of the primary name. Omit to leave unchanged." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / placeType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}."
- Changed
update_repository8 fields changed- changed
Input schema / properties / address / descriptionPrevious 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." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / name / descriptionPrevious value: -"Name. Omit to leave unchanged."New value: +"New name. Omit to leave unchanged." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / repoType / descriptionPrevious 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\")." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / url / descriptionPrevious 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."
- Changed
update_source11 fields changed- changed
Input schema / properties / abbrev / descriptionPrevious value: -"Abbreviation. Omit to leave unchanged."New value: +"New abbreviation. Omit to leave unchanged." - changed
Input schema / properties / attributes / descriptionPrevious 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." - changed
Input schema / properties / author / descriptionPrevious value: -"Author. Omit to leave unchanged."New value: +"New author. Omit to leave unchanged." - changed
Input schema / properties / handle / descriptionPrevious 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." - changed
Input schema / properties / isPrivate / descriptionPrevious value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged." - changed
Input schema / properties / mediaHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / noteHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / pubinfo / descriptionPrevious value: -"Publication info. Omit to leave unchanged."New value: +"New publication info. Omit to leave unchanged." - changed
Input schema / properties / repositoryHandles / descriptionPrevious 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." - changed
Input schema / properties / tagHandles / descriptionPrevious 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\":\"…\"}." - changed
Input schema / properties / title / descriptionPrevious value: -"Title. Omit to leave unchanged."New value: +"New title. Omit to leave unchanged."
30 tool updates
v2.2.0- First observed
add_event_to_person - First observed
create_citation - First observed
create_event - First observed
create_family - First observed
create_note - First observed
create_person - First observed
create_place - First observed
create_repository - First observed
create_source - First observed
create_tag - First observed
delete_object - First observed
get_bookmarks - First observed
get_object - First observed
get_person_tree - First observed
get_recent_changes - First observed
get_reference - First observed
get_relations - First observed
get_timeline - First observed
list_objects - First observed
quick_add_person - First observed
search - First observed
update_citation - First observed
update_event - First observed
update_family - First observed
update_media - First observed
update_note - First observed
update_person - First observed
update_place - First observed
update_repository - First observed
update_source
TDQS
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.45AGPL 3.0
- AlicenseAqualityBmaintenanceMCP server that lets AI agents (Claude, Cursor) debug your .NET / ASP.NET Core app2715MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to search, retrieve, and create genealogical records in a Gramps Web instance.6 npm4MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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