Skip to main content
Glama
ianderso

gramps-evidence-mcp

by ianderso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

add_event_ref

Share an existing event with another person in a role (e.g., census, residence) so citations and corrections apply to all. Refused if the person already has it.

Instructions

Share an existing event with another person, in a role.

For one census entry, residence or burial that several people took part in: each references the same event, so its citations and later corrections serve all of them. Refused if the person already has it. A new fact is add_event_to_person.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
roleNoThe person's role in it: 'Primary', 'Witness', 'Informant', 'Godparent', 'Family', 'Clergy', or a custom role the tree already has.Primary
eventYesHandle or gramps_id of the EXISTING event, e.g. 'E0007'.
personYesHandle or gramps_id of the person to add the event to.
allow_new_typeNoAccept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.0
    • addedInput schema / properties / allow_new_type
      Added value: +{
+  "default": false,
+  "description": "Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names.",
+  "type": "boolean"
+}
  2. Addedv1.0.1

TDQS

A4.5/5.0
Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuine behavioral context beyond that: the 'Refused if the person already has it' precondition (consistent with idempotentHint=false) and the shared-citations correction-propagation rationale. It does not spell out what the new reference fact looks like on return, but the mutation semantics are well disclosed.

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 purpose sentence, then a rationale example, then the sibling exclusion, then the refusal precondition. Efficient and well-ordered. The middle explanatory sentence is slightly prose-heavy but each clause earns its place by justifying the shared-reference design.

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?

For a 4-param mutation tool with no output schema, the description supplies the when-to-use rationale, the sibling routing, and the refusal condition. Annotations cover safety. Return-shape details are the only minor gap, and no output schema exists to carry them.

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 already 100% and describes all four params in detail (role enum values, event examples, allow_new_type behavior). The description augments this by explaining why one would reference an existing event rather than create a new fact, and the role concept ('in a role') frames the role param's purpose. It adds intent-level meaning, though not new syntax.

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

Purpose5/5

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

States a specific verb+resource ('Share an existing event with another person, in a role') and, crucially, contrasts against the closest sibling: 'A new fact is add_event_to_person.' An agent can distinguish the reference-existing-event case from creating a new event without opening either schema.

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

Usage Guidelines5/5

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

Gives an explicit use case ('For one census entry, residence or burial that several people took part in: each references the same event, so its citations and later corrections serve all of them') and names the alternative (add_event_to_person) with the condition that selects it. Also states a refusal precondition ('Refused if the person already has it').

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