Skip to main content
Glama
Sign In
Scormave

Gramps Web MCP

by Scormave
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Create Note

create_note

Create a free-text note of a specified type and return its handle, Gramps ID, and type so you can attach it to people, families, events, places, sources, or citations.

Instructions

Create a free-text note (research notes, transcriptions, comments) of a given type. Returns the new handle, Gramps ID and type, with next steps. The note is attached to nothing yet: add its handle to the noteHandles of each person, family, event, place, source or citation it belongs to (their update tool, linkMode add). For the transcript of a cited record use type Transcript and attach the note to that citation. Change an existing note with update_note. An unknown type is rejected before anything is saved. For several new records that link to each other, such as the people, events, source and citation of one register entry, use create_records instead: one transaction, all created or none. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it.

Input Schema

NameRequiredDescriptionDefault
textYesThe note text (required).
formatNoText format: Plain (default) or Html.Plain
noteTypeNoNote type, default General; e.g. Research, Transcript, Person Note, Event Note, Citation. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: "types").General
isPrivateNoMark the note private (default false).
tagHandlesNoTags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv2.3.0
    • changedInput schema / properties / format / description
      Previous value: -"Text format: Plain or Html (default: Plain)"New value: +"Text format: Plain (default) or Html."
    • changedInput schema / properties / isPrivate / description
      Previous value: -"Mark as private (optional)"New value: +"Mark the note private (default false)."
    • changedInput schema / properties / noteType / description
      Previous value: -"Note type key. Type values are validated by the server; see gramps://types resource or call get_reference(topic: \"types\") for available values. Default General."New value: +"Note type, default General; e.g. Research, Transcript, Person Note, Event Note, Citation. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: \"types\")."
    • changedInput schema / properties / tagHandles / description
      Previous value: -"Tag handles (optional). Handles: JSON array [\"h1\",\"h2\"], a single handle as a plain string, comma/semicolon/newline-separated list, or a JSON-array string. Array entries may be strings or objects {\"ref\":\"…\"} / {\"handle\":\"…\"}."New value: +"Tags. Handles, not Gramps IDs: JSON array [\"h1\",\"h2\"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {\"ref\":\"…\"}."
    • changedInput schema / properties / text / description
      Previous value: -"Note body text (required)."New value: +"The note text (required)."
  2. First observedv2.2.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, it discloses that the note is created unattached, that an unknown type is rejected before anything is saved, that writes are serialized one at a time, that a Gramps Web account with edit permission on the tree is required, and that locked/rate-limited writes return a retry delay. It also states the return payload (handle, Gramps ID, type) despite no output schema.

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?

Purpose and return value are front-loaded, then linking workflow, then alternatives and write constraints. Every sentence carries information, though the multi-clause final sentence about locking and rate limits is dense and could be split.

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?

No output schema exists, yet the description names what is returned and how to use the returned handle. Combined with the attachment workflow, type validation, and concurrency/permission constraints, an agent has everything needed to call it correctly and follow up.

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 100%, so the baseline is 3, but the description adds real semantics on top: the noteType value to use for cited-record transcripts, the validation behavior for unknown types, and the fact that the note is not auto-linked to anything. It does not elaborate on format, isPrivate or tagHandles beyond the schema, keeping it short of a 5.

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 ('Create a free-text note') plus the content kinds it covers (research notes, transcriptions, comments) and the type parameter. It is clearly separable from update_note (change) and create_records (multi-record transactions), both of which are named.

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?

Explicitly routes: use update_note to change an existing note, use create_records when several new records link to each other in one transaction, and use type Transcript for the transcript of a cited record. It also states the non-obvious follow-up (attach the returned handle to noteHandles on the owning object via its update tool with linkMode add).

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