Skip to main content
Glama

manage_citation

Create, retrieve, update, or delete Gramps citation records to manage sources and evidence for genealogy data. Use actions get, create, update, or delete with citation handles and JSON payloads.

Instructions

Create, read, update or delete Gramps Citation records. Writes: create, update, delete.

action=get lists citations (handle empty) or returns one citation by handle. action=create posts a full Citation JSON object in data; action=update PUTs data to /citations/; action=delete removes it. Citation payload fields: gramps_id, source_handle, date, page, confidence, note_list, media_list, change, ... . Attach a citation to a Person/Family/Event by adding its handle to that object's citation_list.

Args: action: The operation, "get", "create", "update" or "delete". handle: Citation handle; required for get-one, update, delete. data: The Citation object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.

Returns: dict: {"status", "url", "data"}.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataNo
queryNo
actionYes
handleNo
instanceNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden, and it discloses the important behavioral traits: HTTP methods for each write action, handle requirements, the fact that get with absent handle returns a list, and the return shape {'status', 'url', 'data'}. It highlights 'Writes: create, update, delete' so agents know mutations are involved. It does not cover error behavior or pagination, but it is transparent about the core operation semantics.

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?

The description is well-structured with sections for purpose, action behaviors, payload fields, arguments, and returns. It is front-loaded with the overall purpose. There is minor redundancy: 'Create, read, update or delete' is immediately followed by 'Writes: create, update, delete,' which adds little. Overall it earns its length, but a small trim would improve conciseness.

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?

Given the absence of annotations and output schema, the description covers the essentials: purpose, per-action semantics, parameter requirements, expected payload fields, return format, and instance default. It also explains how to attach citations to other Gramps objects, which addresses cross-tool usage. Missing details include pagination for list reads, error/status value ranges, and concrete query parameter examples, but these are minor given the tool's CRUD nature.

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

Parameters5/5

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

Schema description coverage is 0%, so the description's parameter explanations are essential and well-delivered. It explains each of the five parameters, including action-specific requirements (handle needed for get-one/update/delete, data required for create/update), and it enumerates Citation payload fields beyond the schema. This adds substantial meaning that the input schema alone lacks.

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 precise statement of scope: 'Create, read, update or delete Gramps Citation records.' It further distinguishes the tool from siblings by detailing Citation-specific fields (source_handle, gramps_id, citation_list) and how citations attach to Person/Family/Event objects. This makes the tool's resource and actions unambiguous.

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?

The description clearly explains when each action applies: get with empty handle lists citations, get with handle returns one, create/update/delete operate on a specific citation. It also provides integration guidance ('Attach a citation to a Person/Family/Event by adding its handle to that object's citation_list'). However, it does not explicitly name alternatives or say when not to use this tool, though the sibling names make the resource boundary clear.

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