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

Convert a whole document

geml_to
Read-only

Convert a WHOLE document and get the result back as text — the read half of the CLI's geml <file> --to <fmt>. to: "geml" on a Markdown file is the importer, the one thing the block tools cannot do; to: "md" projects a GEML document out (lossy); to: "json" returns the full document model, for when geml_list plus geml_get is not enough. Nothing is written — pass the result to geml_add or geml_set to land it. to: "html" also works but returns a whole self-contained page, usually tens of kilobytes this server cannot save: prefer the CLI (geml <file> --to html -o out.html) unless you want the markup in the conversation. A document with errors returns its diagnostics instead of a conversion, and a file that is not under the server root is an error. 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
toNoTarget format. Default is the CLI's: a GEML input becomes json, a Markdown input becomes geml. `html` is a whole page — large, and not writable from here.
fromNoOverride the input format, which is otherwise inferred from the extension (.md -> md, .json -> json, else geml).
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.
sourceYesThe document's full text. This server keeps no files: what you send is the document.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only give readOnlyHint=true and openWorldHint=false; the description adds substantial context beyond that — nothing is written, documents with errors return diagnostics, out-of-root files are errors, the server is stateless, and cross-document references report `unresolvable-document`. It also flags the lossy md projection and the large html output.

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-loads the core purpose before the format-by-format detail, and every clause carries information. It is a dense single paragraph with several parenthetical asides, which slightly hurts scanability for a 4-parameter tool.

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?

With no output schema, the description carries the return-value burden and does so: text result, diagnostics on error, whole-page html. The stateless model and cross-document limitation are also disclosed, so nothing an agent needs 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema by characterizing each `to` value (geml=importer, md=lossy, json=full model, html=self-contained page). The `from`/`name` semantics are largely left to the schema, so it stops 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 (convert) and resource (a whole document), and immediately distinguishes itself from the block-level siblings by naming geml_list and geml_get. Each target format's purpose is spelled out, so an agent can tell it apart from geml_add/geml_set 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes usage: `to: "json"` for when geml_list plus geml_get is not enough, CLI preferred for html, and 'pass the result to geml_add or geml_set to land it.' It names the alternative path and the condition that selects it, including the one thing block tools cannot do (Markdown import).

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