Skip to main content
Glama
ianderso

gramps-evidence-mcp

by ianderso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

update_person

DestructiveIdempotent

Edit a person's gender, primary name, or privacy flag in Gramps. Replacing the primary name keeps the old one as an alternate so its record link is not lost.

Instructions

Edit a person's gender, primary name, or privacy flag.

Replacing the primary name preserves the old one as an 'Also Known As': a name in the tree came from some record, and dropping it loses the link to whatever document used it. To add a name without replacing the primary one, use add_alternate_name.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoNew PRIMARY name. The current primary name is kept as an alternate rather than discarded, unless keep_old_as_alternate is False.
genderNofemale, male, or unknown.
personYesPerson handle or gramps_id (e.g. 'I0001').
reasonNoWhy the old form is not kept. Required with keep_old_as_alternate=False.
privateNoGramps private flag.
keep_old_as_alternateNoFalse only to fix a data-entry error -- a name split wrongly between given and surname, a typo no record contains -- where keeping the old form would invent a variant. The name is then corrected in place, keeping its citations, and reason is recorded in a note on the person.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.0.1
    • addedInput schema / properties / keep_old_as_alternate
      Added value: +{
+  "default": true,
+  "description": "False only to fix a data-entry error -- a name split wrongly between given and surname, a typo no record contains -- where keeping the old form would invent a variant. The name is then corrected in place, keeping its citations, and reason is recorded in a note on the person.",
+  "type": "boolean"
+}
    • changedInput schema / properties / name / description
      Previous value: -"New PRIMARY name. The current primary name is kept as an alternate rather than discarded."New value: +"New PRIMARY name. The current primary name is kept as an alternate rather than discarded, unless keep_old_as_alternate is False."
    • addedInput schema / properties / reason
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Why the old form is not kept. Required with keep_old_as_alternate=False."
+}
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already flag this as destructive, non-idempotent-disabled (idempotentHint=true), and a write, but the description adds substantial behavior beyond them: replacing a name preserves the old one as an 'Also Known As' because dropping it severs the link to the source record, and the keep_old_as_alternate=False path corrects in place, retains citations, and records a reason in a note. This is exactly the kind of consequence disclosure a mutation tool needs.

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

Conciseness5/5

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

Three tight sentences with the scope front-loaded, followed by the preservation rationale and then the sibling routing. Every sentence carries information the agent needs; nothing is padding.

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 6-parameter mutation tool with full schema coverage and no output schema, the description supplies what the schema cannot: destructive consequences of name replacement, the rationale, and when to prefer a sibling. Nothing essential for a correct call appears to be missing.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, and the description adds real meaning on top: the name parameter's preservation semantics and the keep_old_as_alternate flag's intent and side effects (citations kept, reason noted). It does not re-document fields like gender or private, which the schema already covers adequately.

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

Purpose5/5

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

States a specific verb (edit) applied to a specific resource (a person), and names exactly which attributes are editable: gender, primary name, privacy flag. It also distinguishes itself from the sibling add_alternate_name, so an agent can route correctly without inspecting schemas.

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

Usage Guidelines4/5

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

Gives a clear routing rule for the main ambiguous case: 'To add a name without replacing the primary one, use add_alternate_name.' It also explains the narrow condition under which keep_old_as_alternate=False is legitimate. It lacks a broader when-to-use/when-not framing for non-name edits, but the critical alternative is explicit.

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

Deploy Server

Other Tools