Skip to main content
Glama
ianderso

gramps-evidence-mcp

by ianderso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

cite_object

Attach a citation to a person, family, name, or other object when the claim is not a dated event, such as a couple relationship.

Instructions

Attach a citation to any object that carries one -- not just events.

cite_event covers facts; this covers the rest. The important case is the FAMILY, whose citation supports a claim no event makes: that these two people were a couple. Person-level citations are for evidence about the individual as a whole (an identity document) rather than about one dated fact -- prefer citing the specific event where one exists.

A NAME is cited with object_type='name': "this record gives this spelling" is narrower than evidence about the person. To cite a parent-child link, use cite_child_link: that is a different claim and needs its own citation.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
refYesHandle or gramps_id of the object to cite.
nameNoWith object_type='name': which of the person's names, e.g. {'surname': 'Bittner', 'type': 'Birth Name'} or {'primary': true}. Must match exactly one.
citationYesCitation to attach.
object_typeYesperson, family, event, place, media, source, citation, or name (one of a person's names: ref is the person, name says which).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.0.1
    • addedInput schema / $defs / NameMatch
      Added value: +{
+  "additionalProperties": false,
+  "description": "Which of a person's names. Every field given must match, ignoring case.\n\nget_person lists the names: the primary, and each alternate with its index.",
+  "properties": {
+    "given": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Given name(s) as stored."
+    },
+    "index": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Position among the alternate names, as get_person lists them. Only needed to tell identical duplicates apart."
+    },
+    "primary": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "True: the primary name only. False: alternate names only."
+    },
+    "surname": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Surname as stored."
+    },
+    "type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Name type: 'Birth Name', 'Also Known As', 'Married Name', ..."
+    }
+  },
+  "type": "object"
+}
    • addedInput schema / properties / name
      Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/NameMatch"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "With object_type='name': which of the person's names, e.g. {'surname': 'Bittner', 'type': 'Birth Name'} or {'primary': true}. Must match exactly one."
+}
    • changedInput schema / properties / object_type / description
      Previous value: -"person, family, event, place, media, source, or citation."New value: +"person, family, event, place, media, source, citation, or name (one of a person's names: ref is the person, name says which)."
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so the safety story is covered. The description adds domain semantics about which claims a citation supports, but says nothing about side effects, whether a new citation object is created, or what happens to an existing citation on re-cite. Useful context, but not rich behavioral disclosure beyond 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.

Conciseness4/5

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

Front-loaded with the core action and scope, then organized as distinct routing paragraphs. Every sentence maps to a real decision, though the prose is dense and the family/name cases could be tighter.

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

Completeness4/5

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

Covers scope, alternatives, and the tricky name/family/link cases well, and the schema fully documents the citation precedence. It stops short of describing the return value or failure mode (e.g. a name match that matches zero or multiple names), which would matter for a non-idempotent mutation with no output schema.

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

Parameters3/5

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

Schema coverage is 100% and CitationInput's precedence rules are fully spelled out in the schema, so the baseline is 3. The description reinforces the object_type='name' case and the family case but adds no new syntax or format detail beyond what the schema already documents.

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

Purpose5/5

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

States a specific verb and resource ('Attach a citation to any object that carries one') and immediately scopes it against the sibling cite_event ('cite_event covers facts; this covers the rest'). An agent can distinguish this from cite_event and cite_child_link without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules: events go to cite_event, parent-child links to cite_child_link, person-level citations only for whole-person evidence, names via object_type='name'. It even states a preference ('prefer citing the specific event where one exists'), which is exactly the when-not guidance an agent needs.

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