Agentic Mermaid

Edit Mermaid diagram

mutate

Read-onlyIdempotent

Apply a list of structured edit ops to an existing Mermaid source and return the edited diagram. This is the declarative counterpart to execute: plain JSON in, plain JSON out, no sandbox. Prefer it for straightforward edits; reserve execute for logic the ops don't express. Returns { ok, family, source, verify:{ ok, warnings } } on success, or { ok:false, family, opIndex, error } — where error names the offending field and lists the valid ones — when an op is malformed or cannot apply. Ops apply in order and are all-or-nothing: the first failing op stops the batch (its position is opIndex) and the input is left untouched. Each op is { "kind": , …fields }. Call describe_sdk for the detected family before authoring unfamiliar ops; it returns compact signatures or exact field types, enum values, defaults, and constraints. Set mode to source-preserving for supported edits to opaque Class or Flowchart source. Exact edited bytes and portability warnings are retained; unsupported operations still fail atomically. This mode does not promise portable export.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "source": "<source>",
      "ops": "<ops>"
    },
    "name": "mutate"
  }
}

Input Schema

Name	Required	Description	Default
`ops`	Yes	Non-empty ordered list of edit ops; each is { kind, ...fields }.
`mode`	No	Source-preserving mode edits owned source ranges without regenerating unsupported syntax.	structured
`source`	Yes	Mermaid source to edit.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 1, 2026

addedInput schema / properties / mode

Added value: +{
+  "default": "structured",
+  "description": "Source-preserving mode edits owned source ranges without regenerating unsupported syntax.",
+  "enum": [
+    "structured",
+    "source-preserving"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedJul 16, 2026

changedInput schema / properties / ops / description

Previous value: -"Ordered list of edit ops; each is { kind, ...fields }."New value: +"Non-empty ordered list of edit ops; each is { kind, ...fields }."

addedInput schema / properties / ops / minItems
```
Added value: +1
```

Changed1 schema field changedJul 14, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
First observedJul 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing transactional semantics ('ops apply in order and are all-or-nothing', 'input is left untouched' on failure), the exact success and failure return shapes, that `opIndex` locates the failing op, and the caveat that source-preserving mode 'does not promise portable export'. The pure-function framing ('plain JSON in, plain JSON out, no sandbox') is consistent with readOnlyHint=true, since no external state is modified.

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, then layered: routing, return contract, atomicity, op shape, prerequisite, mode caveat. Dense and nearly waste-free, though the routing and counterpart framing overlap slightly ('declarative counterpart to execute' vs. 'prefer it... reserve execute').

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, and the description compensates fully by spelling out both return shapes. For a 3-parameter transformation tool with nested free-form op objects, everything an agent needs to call it correctly — op structure, failure behavior, mode selection, prerequisite lookup — is present.

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 adds real meaning on top by specifying the op object shape `{ "kind": <op>, …fields }`, that ordering matters, and what source-preserving mode actually trades off (retains exact edited bytes, portability warnings). It stops short of naming individual op kinds or their fields, deferring that to `describe_sdk`.

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 ('Apply a list of structured edit ops to an existing Mermaid source and return the edited diagram') and immediately positions itself against the sibling `execute` as the declarative, sandbox-free counterpart. An agent can distinguish `mutate` from `execute`, `build`, or `verify` 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?

Explicit routing rules: 'Prefer it for straightforward edits; reserve `execute` for logic the ops don't express', plus a prerequisite instruction to call `describe_sdk` before authoring unfamiliar ops, plus a conditional rule for when to set `mode: source-preserving`. Both when-to-use and when-to-use-something-else are covered.

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

All Agentic Mermaid tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.