Skip to main content
Glama
ianderso

gramps-evidence-mcp

by ianderso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

add_source

Create a Gramps Source record for a record set, book, certificate, or website so you can cite it through Citations and link it to a Repository.

Instructions

Create a Source (a body of evidence: a record set, book, certificate, website).

In the Gramps evidence model a Source is what you cite through a Citation. Create the source once, then create citations against it for each fact it supports. Optionally link it to a Repository (where the source is held).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
titleYesSource title, e.g. '1900 U.S. Federal Census'.
authorNoAuthor/creator of the source.
media_typeNoMedium of the source at that repository, e.g. 'Book', 'Film', 'Electronic'. Only used with repository.Unknown
repositoryNoRepository handle/gramps_id that holds this source.
call_numberNoCall number / reference within the repository.
abbreviationNoShort abbreviation.
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.
publication_infoNoPublication info (publisher, date, series).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields 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"
+}
    • changedInput schema / properties / media_type / description
      Previous value: -"Medium of the source at that repository, e.g. 'Book', 'Microfilm', 'Electronic'. Only used with repository."New value: +"Medium of the source at that repository, e.g. 'Book', 'Film', 'Electronic'. Only used with repository."
  2. Changed1 schema field changedv1.0.1
    • addedInput schema / properties / media_type
      Added value: +{
+  "default": "Unknown",
+  "description": "Medium of the source at that repository, e.g. 'Book', 'Microfilm', 'Electronic'. Only used with repository.",
+  "type": "string"
+}
  3. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover the safety profile (write, non-destructive, non-idempotent, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: the evidence-model relationship to citations and the optional repository link. It stops short of operational details such as duplicate handling on a non-idempotent create or what the call returns.

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?

Four sentences, front-loaded with the definition and then the workflow, with no filler. The parenthetical gloss on 'Source' and the citation relationship both earn their space, though the text is slightly longer than strictly needed for an 8-param create tool.

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 create tool with full schema coverage and safety annotations, the description supplies the domain framing an agent needs to call it correctly. No output schema exists, so the return value is unspecified, and duplicate/error behavior for a non-idempotent create is left implicit — the only notable gaps.

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 description coverage is 100% and every one of the 8 parameters is documented in the schema itself (title, author, repository, call_number, allow_new_type, etc.). The description adds no parameter-level syntax or format guidance, so the baseline of 3 is appropriate.

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 (Create) plus resource (Source) and defines the resource in domain terms ('a body of evidence: a record set, book, certificate, website'). It also separates itself from the closely-related add_citation by explaining that a Source is cited *through* a Citation, so an agent can distinguish the two without opening a schema.

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 real context: create the source once, then create citations against it per fact, and optionally link it to a Repository. This tells the agent where add_source sits in the workflow, but it never states a when-not (e.g. use update_source for existing sources, or what to do if it may already exist).

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