Skip to main content
Glama
Scormave

Gramps Web MCP

by Scormave
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Create Note

create_note

Create a free-text note (research, transcript, comment) of a chosen type for Gramps Web records, returning its handle, Gramps ID, and type for later linking.

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). Change an existing note with update_note. An unknown type is rejected before anything is saved.

Input Schema

TableJSON 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.6/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false / destructiveHint=false; the description goes well beyond by disclosing the return payload (handle, Gramps ID, type), that the note starts unattached (a non-obvious post-condition), and that an unknown type is rejected before anything is saved (atomic failure semantics). That is real behavioral value not present in structured fields.

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 return value, then the attachment workflow and the alternative tool. Dense but nearly every clause carries operational information; only the note-type rejection clause overlaps with the schema.

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?

For a mutating create tool with no output schema, the description supplies the return shape, the unattached-state caveat, the linking follow-up, and failure behavior. Nothing an agent needs to call it correctly and handle the result is missing.

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%, so all five parameters are already documented including type validation and the get_reference(topic: "types") lookup. The description's note-type mention largely restates the schema, so the baseline 3 applies rather than a higher score.

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 ("Create a free-text note") plus the scope (research notes, transcriptions, comments) and the returned identifiers. It explicitly contrasts with the sibling update_note, so an agent can route between creation and editing 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 explicit when-to-use (new note), when-to-use-instead ("Change an existing note with update_note"), and the follow-up workflow: attach the returned handle to noteHandles of the owning person/family/event/place/source/citation via their update tool with linkMode add. Alternatives and prerequisites are both named.

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