One section in, one section out — on Markdown/GEML files, bad writes refused.
Scored across 9 tools
Each tool targets a distinct operation and the descriptions actively contrast overlapping ones (geml_add vs geml_set vs geml_delete, geml_find vs geml_list, geml_rename vs geml_set). An agent can tell exactly which tool applies to a given editing intent, and the read/write/convert boundaries are explicit.
All tools share a clean geml_<verb> snake_case pattern (add, check, delete, find, get, list, rename, set). The lone deviation is geml_to, which is a preposition rather than a verb, though it deliberately mirrors the CLI's `--to` flag.
Nine tools is well-scoped for a document-format editing server, covering the read/write/validate/convert surface without redundancy. Every tool earns its place and none feels padded.
The core lifecycle (list, get, find, add, set, delete, rename, check, to) is covered, but geml_revert is referenced repeatedly as the undo mechanism for deletions and renamed/replaced content yet is not actually exposed. This dead-end reference will cause agent failures when trying to undo a write.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The 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. | |
| anchor | No | The block the insertion is relative to — an id, or any address geml_list prints; it must name one block. Required for before/after | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. | |
| content | Yes | The GEML fragment to insert | |
| position | Yes | Where to insert |
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.
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.
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.
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.
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.
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.
Validate a GEML document without changing it: returns every diagnostic with a stable code, a severity and a line, and an empty list means the document is valid. Use it to confirm a document is sound before reporting work as finished. Every write through this server runs the same check before it lands, so a refused write already carries this information. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The 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. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the server is STATELESS, that no files are kept, that `source` is the entire document, that writes return a `document`, and that cross-document references like `[[other.geml#id]]` cannot be resolved here and surface as `unresolvable-document`. These is exactly the non-obvious context an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and return shape, then usage, then the stateless caveat. Every sentence carries information, though the final sentence packs three separate facts (statelessness, write round-trip, unresolvable references) and runs long. Dense rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the full burden of describing return values and does so precisely. Combined with the stateless-model explanation and the meaning of an empty diagnostic list, an agent has everything needed to call and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both `name` (GEML vs Markdown dispatch) and `source` are already fully documented in the schema. The description reinforces that the document travels in `source` and that nothing is persisted, but adds no format or syntax detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Validate a GEML document without changing it') and immediately defines what comes back: diagnostics with a stable `code`, severity and line, plus the empty-list-means-valid rule. This distinguishes it cleanly from the mutation siblings (geml_add, geml_set, geml_delete) 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to reach for it ('confirm a document is sound before reporting work as finished') and when it is redundant ('every write through this server runs the same check before it lands, so a refused write already carries this information'). It also states the boundary condition for the stateless model, so the agent knows an `unresolvable-document` diagnostic is expected rather than a bug.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one or more blocks, each named by an id or any address geml_list prints; a filter (=== type, {key=value}) removes every block it matches. Each block takes the blank line that separated it from its neighbours, so deleting what geml_add inserted leaves the file as it was. To undo a deletion, geml_revert the removed id; to change a block rather than remove it, use geml_set. References left pointing at a removed block come back as diagnostics but do NOT block the deletion — read them, then repair the references or revert. A selector that names nothing is skipped, so repeating a call changes nothing. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | The blocks to remove: ids or addresses | |
| name | No | The 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. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavior: the block consumes its trailing blank line (so deleting what geml_add inserted restores the file), references come back as diagnostics but do not block deletion, refusals return ok:false with a hint and leave the file unchanged, and the server is STATELESS so cross-document references surface as unresolvable-document. No contradiction with annotations; idempotency and destructiveness are both corroborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and selector semantics, then alternatives, then edge cases and return shape — a sensible ordering. It is dense and delivered as a single long paragraph rather than scannable segments, so a little structure is lost, but nearly every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 contract (`{ok, file, diagnostics, revision}`, optional `notes`, refusal shape) and the stateless document-in/document-out model. For a destructive, stateless write tool this is complete enough to invoke correctly without further discovery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning the schema lacks: the ids array accepts filter syntax (`=== type`, `{key=value}`) that removes every matching block, and addresses are those geml_list prints. The `source`/stateless model is also reinforced in prose, not just in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource ('Remove one or more blocks') and defines the acceptable selectors (ids or any address geml_list prints, plus `=== type` / `{key=value}` filter syntax). It explicitly distinguishes itself from geml_add (what it undoes), geml_set (change rather than remove), and geml_revert (undo), so an agent can route without opening a sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit alternatives with conditions: 'to undo a deletion, geml_revert the removed id; to change a block rather than remove it, use geml_set.' It also covers the no-match case ('a selector that names nothing is skipped') and how to handle dangling references, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search block CONTENT in the document; each hit is one <name>\t<address> row. geml_list says what a document contains, this says which block holds the words — as an address that pastes straight into geml_get or geml_set, not a line number the next edit invalidates. The address is the innermost block holding the match, and a block matching on many lines is reported once. Substring, case-insensitive unless case is true. No match is an empty result, not 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.
| Name | Required | Description | Default |
|---|---|---|---|
| case | No | Match case exactly (default: case-insensitive) | |
| head | No | Add the matching line as a third column | |
| name | No | The 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. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. | |
| within | No | Optional: only look inside the blocks this selector names, e.g. `#install` for a section or `=== table` for every table. It takes the same selector forms as geml_get's `id`. | |
| pattern | Yes | Text to look for inside block bodies |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds genuinely new behavioral facts: no match yields an empty result rather than an error, matching is substring and case-insensitive by default, the address is the innermost containing block, and cross-document `[[...#id]]` references cannot resolve in a stateless server and surface as `unresolvable-document`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and scope, then progressively less essential detail; little is wasted since the statelessness note and error semantics are operationally important. The long compound sentences and heavy backtick/semicolon use make it denser than it needs to be, but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no enum constraints, the description carries the full burden and does so: it defines the return row format, no-match behavior, error token, and the stateless source/document contract. An agent can invoke and interpret results without further inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 semantics the schema does not carry: the innermost-block resolution rule, the effect of the implied search scope (contrast with `within`), and the case-insensitive default that `case` overrides. These clarify parameter behavior rather than restating field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search block CONTENT in the document') plus the exact output shape ('each hit is one `<name>\t<address>` row'). It explicitly distinguishes itself from the sibling geml_list by contrasting 'what a document contains' with 'which block holds the words'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative (geml_list) and the condition that selects this tool instead, and further routes the agent downstream by saying the returned address 'pastes straight into geml_get or geml_set'. The when-not case (a block matching many lines is reported once, no line numbers) is also stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read ONE block from a GEML document instead of the whole file: only that block comes back, typically a few percent of the document. Pass the address geml_list prints as id — it also reaches blocks with no #id; to locate a block by its words instead, use geml_find first. An id that matches nothing, or a file that is not under the server root, is an error naming it. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | What to read: a block id (with or without `#`), a `## Heading` line (its whole section), `=== type` for every block of a type, `=== code {lang=py}` or `{.warn}` for every block carrying those attributes, a `@<hex>` content address for a block with no id, or `L27`/`L27-58` for the smallest block holding those lines — the forms `geml_list` prints, plus the line numbers an editor or a diff hunk speaks | |
| name | No | The 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. | |
| part | No | How much of the block to return (default: whole). For a SECTION these cut it three ways: `head` is the heading line, `intro` everything under it up to its first subheading, `body` everything under it — so `body` always contains `intro`, and equals it when the section has no subheading. Reach for `intro` to read a section's opening without pulling its subsections into the conversation; a whole `#id` on a top-level heading is often the entire document. Only a heading has an intro. `body` is usually what you want together with `view`. | |
| view | No | Read THROUGH an `embed` block to the entity block it stands for, following a multi-layer chain to its end. An `embed` has no content of its own, so this is the only way to see what it points at; on any other block it changes nothing. Returns {from, content}: `from` names the document the content actually came from, and its references and relative paths resolve against THAT document, not this one. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. | |
| within | No | Optional: only look inside the blocks this selector names, e.g. `#install` for a section or `=== table` for every table. It takes the same selector forms as geml_get's `id`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations say read-only and closed-world, but the description adds substantive behavior beyond them: the server is STATELESS, the document travels in `source`, writes come back as `document` for the caller to save, unmatched ids and out-of-root files are named errors, and cross-document references report `unresolvable-document`. These are real operational constraints an agent must know before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and the id-source instruction; the statelessness caveat is the only tail-heavy part. Dense but every sentence carries information — no filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still covers what comes back (just the block, and {from, content} for `view`, with `from` redefining relative-path resolution). Error behavior, statefulness, and cross-document limits are all disclosed, leaving no material gap for a read-only tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 cross-tool meaning the schema cannot: the `id` is the address geml_list emits and also reaches blocks with no `#id`, and `view` is 'the only way to see what an embed points at'. The statelessness note explains why `source` exists at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource with explicit scope: 'Read ONE block from a GEML document instead of the whole file'. The contrast with whole-document reading and the pointer to geml_list/geml_find cleanly separates it from its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States where the `id` comes from ('the address geml_list prints as `id`') and names the alternative route ('to locate a block by its words instead, use geml_find first'), which is explicit when/when-not/alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every addressable block in a GEML document — its address, kind and heading text — in one call, with no paging. Call this FIRST: what it returns is what every other tool here addresses, and it is cheaper and more reliable than reading the file to see what is in it. Rows marked anon have no #id; geml_get and geml_set take their address as id, while the other write tools need a real id, so give such a block one first. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The 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. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. | |
| within | No | Optional: only look inside the blocks this selector names, e.g. `#install` for a section or `=== table` for every table. It takes the same selector forms as geml_get's `id`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declared, the description still adds substantial context beyond annotations: no paging, error behavior for out-of-root files, stateless server semantics (document travels in `source`, writes return `document`), and the `unresolvable-document` outcome for cross-document references. This is unusually rich behavioral disclosure for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the 'Call this FIRST' directive, and every sentence carries operational information. It is dense and the stateless/cross-reference sentence is long, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by describing the returned fields and the `anon` row marker. Combined with the error and statelessness notes, an agent has everything needed to call this correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents `name`, `source`, and `within` in detail, including the `within` selector forms. The description adds only the stateless note about `source` and does not contribute new syntax or defaults beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List every addressable block in a GEML document') and enumerates the returned fields (address, kind, heading text). It also names sibling tools (geml_get, geml_set, write tools) and how they relate to the output, so an agent can distinguish this from them without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call this FIRST' and justifies it against an alternative ('cheaper and more reliable than reading the file'). It also tells the agent what to do with `anon` rows before calling other tools, covering when-to-use and prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a block id AND every reference to it in the same document, in one id-boundary-safe write. Use this rather than geml_set or a text search-and-replace, which would also hit ids that merely share a prefix. A Markdown heading's anchor is its text, so it is renamed by changing the heading with geml_set (part: head), not here. An old id that does not exist, or a new one already taken, 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.
| Name | Required | Description | Default |
|---|---|---|---|
| new | Yes | New id | |
| old | Yes | Current id | |
| name | No | The 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. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=true), and the description adds substantial context on top: refusal semantics (nonexistent `old`, taken `new`), the returned payload shape, a `notes` channel for side effects, refusal behavior with `hint` and an unchanged file, and the stateless document-in/document-out model including why cross-document refs surface as `unresolvable-document`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core behavior and scope, and each sentence carries distinct information (alternatives, Markdown exception, refusal rules, return shape, stateless model). It is dense and long for a 4-param tool, with the stateless explanation partly restating the schema's 'this server keeps no files', but nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates fully by documenting the return shape (`{ok, file, diagnostics, revision}`, optional `notes`, `ok: false` with `hint`). Combined with the statelessness and cross-document limitation, an agent has everything needed to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning beyond the terse schema text: `old` must exist and `new` must be free or the call is refused, and `name` is what selects GEML vs Markdown interpretation. That is real semantic value over 'Current id' / 'New id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (rename a block id) and immediately narrows scope: it renames the id AND every reference to it in one boundary-safe write. It explicitly distinguishes itself from geml_set and from plain text search-and-replace, so an agent can pick it apart 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance ('Use this rather than geml_set or a text search-and-replace, which would also hit ids that merely share a prefix') and a clear when-not-to-use carve-out: Markdown heading anchors must be changed via geml_set on `part: head`, not here. Alternatives and exclusion conditions are both named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace ONE block and leave every other byte untouched — prefer this to rewriting a file. For content that does not exist yet use geml_add; to remove a block, geml_delete. The replacement is validated before it is written: if it would break the document, nothing is written and the diagnostics come back — fix the body rather than resending it. Removing content is not refused: if the replacement drops blocks, the write goes through and the result names each one, so check it after shortening a section; geml_revert puts one back. part replaces the whole block (default), its head line, a section's intro, or its body. In a Markdown file a heading's anchor is its text, as on GitHub: new heading text gives the heading a new address, and the document's links to the old one follow in the same write. GEML content written over a Markdown heading or prose is converted to Markdown, as in geml_add; a GEML block already in the file stays GEML. An id that matches no block, or several, 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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Which block to replace: an id (with or without `#`), a `@<hex>` content address from `geml_list` for a block with no id, or `L27`/`L27-58` for the smallest block holding those lines. Must match exactly one block | |
| body | Yes | The replacement text | |
| name | No | The 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. | |
| part | No | What to replace (default: whole). `intro` replaces a section's opening — everything under the heading up to its first subheading — and leaves every subsection byte-identical, which is what makes a read-edit-write cycle on a long section safe. An empty intro (a subheading follows the heading immediately) is written into, so this also adds an opening where there was none. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=true, but the description adds substantial behavioral context beyond them: validation happens before the write and a breaking replacement writes nothing, removals are NOT refused (dropped blocks are named in the result), the return shape {ok, file, diagnostics, revision} with optional notes, refusal semantics (ok:false, hint, file unchanged), and the stateless-server constraint that makes [[other.geml#id]] unresolvable. No contradiction with the mutation/destructive annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and sibling routing before the details, so an agent gets the essentials in the first sentence. It is dense and long (~10 sentences), and a few clauses (e.g. the Markdown anchor-and-links aside) could be tightened, but each sentence carries distinct operational information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-param mutation tool with no output schema, the description supplies what's missing: the return payload fields, the refusal shape, the notes mechanism, and the statelessness model that governs how `source`/`document` travel. Nothing an agent needs to call it correctly appears to be omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, but the description meaningfully extends it: it enumerates what `part` targets (whole/head/intro/body) and explains the safety property of `intro` (subsections stay byte-identical), plus the refuse-if-not-exactly-one rule for `id` and how `name` selects GEML vs Markdown parsing. This goes beyond restingating the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first clause states a specific verb and resource (replace ONE block) plus scope (leave every other byte untouched), and immediately differentiates from siblings by naming geml_add for new content and geml_delete for removal. An agent can distinguish this from every other geml_* tool 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: 'prefer this to rewriting a file', use geml_add for nonexistent content, geml_delete to remove, geml_revert to restore a dropped block. It also gives an actionable failure policy — 'fix the body rather than resending it' — which is precisely the guidance an agent needs after a rejected write.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Target 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. | |
| from | No | Override the input format, which is otherwise inferred from the extension (.md -> md, .json -> json, else geml). | |
| name | No | The 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. | |
| source | Yes | The document's full text. This server keeps no files: what you send is the document. |
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.
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.
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.
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.
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.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
geml_addgeml_checkgeml_deletegeml_findgeml_getgeml_listgeml_renamegeml_setgeml_toTurn markdown and Mermaid diagrams into rendered jotbins.com links, and read them back.
Markdown in, any format out. PDFs merged, split, watermarked. Runs on our own doc engines.
PDF, Word, PowerPoint, Excel, HTML, EPUB to Markdown: OCR, page ranges, tables, RAG chunking
LF vs CRLF vs CR, text discarded
Add one secure layer between your agents and this server.