Gramps Web MCP

Overview Schema Source Related Servers Discussions Admin

Update Repository

update_repository

DestructiveIdempotent

Update an existing repository's name, type, address, website, or note and tag links while leaving omitted fields unchanged. Use it to correct repository details without creating a new record.

Instructions

Change an existing repository's name, type, address, website or links to notes and tags. For a new repository use create_repository; to remove one, delete_object. Which sources it holds, with their call numbers, is stored on the sources: change that with update_source (repositoryHandles), not here. address becomes the street line of a single address and url a single Web Home link; each replaces every stored value, and an empty string removes them. A change shows on every source that lists the repository. 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, though the linked records themselves stay in the tree. Returns the handle and Gramps ID; a missing repository returns a not-found message, and an unknown type is rejected before anything is saved. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it.

Input Schema

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":"…"}.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.3.1Oct 7, 2026

changedInput schema / properties / linkMode / description

Previous value: -"How to apply all supplied link lists: replace (default) replaces each full list; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata."New value: +"How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata."

Changed8 schema fields changedv2.3.0Oct 6, 2026

changedInput schema / properties / address / description

Previous value: -"Street line (replaces address list when set). Omit to leave unchanged."New value: +"New postal address as one line; replaces every stored address, and an empty string removes them. Omit to leave unchanged."

changedInput schema / properties / handle / description

Previous value: -"Repository handle. Handle or Gramps ID (e.g. I0001). Handles are opaque strings from the API. Gramps IDs (like I0001, F0023) are auto-resolved to handles. Find handles with search() or list_objects()."New value: +"The repository to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."

changedInput schema / properties / isPrivate / description

Previous value: -"Private flag. Omit to leave unchanged."New value: +"true makes the record private, false public. Omit to leave unchanged."

changedInput schema / properties / name / description

Previous value: -"Name. Omit to leave unchanged."New value: +"New name. Omit to leave unchanged."

changedInput schema / properties / noteHandles / description

Previous value: -"Linked notes. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."

changedInput schema / properties / repoType / description

Previous value: -"Type. Omit to leave unchanged. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values."New value: +"New type, e.g. Archive, Library, Church. Omit to leave unchanged. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: \"types\")."

changedInput schema / properties / tagHandles / description

Previous value: -"Linked tags. Omit to leave unchanged. For link lists, linkMode controls replace/add/remove; [] clears in replace mode and does nothing in add/remove. Other lists always use replacement. Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."

changedInput schema / properties / url / description

Previous value: -"Website URL (replaces url list when set). Omit to leave unchanged."New value: +"New website; replaces every stored link, and an empty string removes them. Omit to leave unchanged."

First observedv2.2.0Oct 3, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations, it discloses that changes propagate to every source listing the repository, that empty strings/empty lists remove stored values, that replace mode can destroy link metadata, that writes are serialized and require edit permission, and that locked/rate-limited writes return retry delays. It also describes the return value and error cases. It is fully consistent with destructiveHint=true and idempotentHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is dense but front-loaded: purpose first, then alternatives, scope boundaries, update semantics, linkMode behavior, returns, and auth/rate-limit behavior. Every sentence carries operational information for a nine-parameter destructive mutation tool.

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

Completeness5/5

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

For a destructive update tool with no output schema, the description is complete: it covers return values, not-found handling, type validation, propagation effects, partial-update behavior, linkMode semantics, authentication requirements, and retry behavior under locking/rate limits.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the prose adds integrated meaning: it explains that address becomes a single street line and url a single Web Home link, that both replace all stored values, and that linkMode governs every supplied link list including [] semantics. This is largely reinforcing the schema, but the cross-parameter interaction is usefully clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: changing an existing repository's name, type, address, website, or links to notes and tags. It explicitly distinguishes itself from create_repository, delete_object, and update_source, so an agent can select it without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when to use this tool versus create_repository for new repositories, delete_object for removal, and update_source for source-to-repository links. It also gives important usage rules: pass only changed fields, omitted arguments stay unchanged, and link lists follow linkMode.

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

Update Repository

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools