Skip to main content
Glama

GEML — a plain-text document format built to be edited in place, one section at a time

by io.github.geml-spec
OverviewDiscussionsAdmin

Insert new content

geml_add

Insert new content — one or more blocks, or prose — at the end of the document (position: append) or before/after the block named by anchor. Use this for content that does not exist yet; to change a block that does, use geml_set. Ids inside the content are kept. In a .md file Markdown lands as written, and GEML content is converted to Markdown as to: "md" converts it, the result's notes saying so; content Markdown cannot hold, such as a view without its source, is refused. Like every write here it is validated first: a missing anchor, an id that clashes with an existing one, or content that would break the document is refused. Returns {ok, file, diagnostics, revision}, with notes when the write did something to say out loud (a block it dropped, an address it changed); a refusal is ok: false with a hint, and the file is unchanged. This server is STATELESS: the document travels in source and a write comes back as document for you to save; it holds no other documents, so a cross-document reference such as [[other.geml#id]] cannot be resolved here and is reported as unresolvable-document.

Input Schema

NameRequiredDescriptionDefault
nameNoThe document's file name, e.g. notes/spec.geml or README.md — it decides whether the text is read as GEML or as Markdown (a `.md` name), and it is how the document is called in messages. Default: document.geml.
anchorNoThe block the insertion is relative to — an id, or any address geml_list prints; it must name one block. Required for before/after
sourceYesThe document's full text. This server keeps no files: what you send is the document.
contentYesThe GEML fragment to insert
positionYesWhere to insert

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations cover the safety profile (not read-only, not destructive, not idempotent), and the description still adds substantial behavior beyond them: Markdown vs GEML conversion on `.md` names, refusal semantics with `ok: false` and a `hint`, the return shape `{ok, file, diagnostics, revision}`, and the stateless cross-document limitation. The only gap is that it does not spell out permission or revision-conflict behavior for concurrent edits.

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 purpose and placement, then the sibling routing, then edge cases — a sound ordering with no filler. It is dense and runs several clauses together in single sentences, which costs some readability, but every sentence carries information an agent needs.

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 5-parameter mutation tool with no output schema, the description covers purpose, the alternative tool, validation/refusal behavior, the returned fields, and the stateless server model that governs how a caller must persist the result. Nothing required to call it correctly is missing.

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%, so the baseline is 3. The description goes further: it explains that `position: append` targets the document end while `anchor` names exactly one block and is required for before/after, and that ids inside `content` are preserved. That meaning is not fully conveyed by the terse schema descriptions.

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 (insert content) plus the exact placement semantics (append or before/after the anchor block). It explicitly contrasts itself with geml_set ('to change a block that does, use geml_set'), so an agent can separate it from siblings without opening any 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 decision rule: use when the content does not exist yet, use geml_set when it does. It also enumerates refusal conditions (missing anchor, id clash, document-breaking content), which tells the agent when a call will fail before it makes one.

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

All GEML — a plain-text document format built to be edited in place, one section at a time toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources